path: root/usr/src/man/man1/ar.1

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
.\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
.\"
.TH AR 1 "Sep 10, 2013"
.SH NAME
ar \- maintain portable archive or library
.SH SYNOPSIS
.LP
.nf
\fB/usr/bin/ar\fR \fB-d\fR [\fB-Vv\fR] \fIarchive\fR \fIfile\fR...
.fi

.LP
.nf
\fB/usr/bin/ar\fR \fB-m\fR [\fB-abiVv\fR] [\fIposname\fR] \fIarchive\fR \fIfile\fR...
.fi

.LP
.nf
\fB/usr/bin/ar\fR \fB-p\fR [\fB-sVv\fR] \fIarchive\fR [\fIfile\fR]...
.fi

.LP
.nf
\fB/usr/bin/ar\fR \fB-q\fR [\fB-cVv\fR] \fIarchive\fR \fIfile\fR...
.fi

.LP
.nf
\fB/usr/bin/ar\fR \fB-r\fR [\fB-abciuVv\fR] [\fIposname\fR] \fIarchive\fR \fIfile\fR...
.fi

.LP
.nf
\fB/usr/bin/ar\fR \fB-t\fR [\fB-sVv\fR] \fIarchive\fR [\fIfile\fR]...
.fi

.LP
.nf
\fB/usr/bin/ar\fR \fB-x\fR [\fB-CsTVv\fR] \fIarchive\fR [\fIfile\fR]...
.fi

.LP
.nf
\fB/usr/xpg4/bin/ar\fR \fB-d\fR [\fB-Vv\fR] \fIarchive\fR \fIfile\fR...
.fi

.LP
.nf
\fB/usr/xpg4/bin/ar\fR \fB-m\fR [\fB-abiVv\fR] [\fIposname\fR] \fIarchive\fR \fIfile\fR...
.fi

.LP
.nf
\fB/usr/xpg4/bin/ar\fR \fB-p\fR [\fB-sVv\fR] \fIarchive\fR [\fIfile\fR]...
.fi

.LP
.nf
\fB/usr/xpg4/bin/ar\fR \fB-q\fR [\fB-cVv\fR] \fIarchive\fR \fIfile\fR...
.fi

.LP
.nf
\fB/usr/xpg4/bin/ar\fR \fB-r\fR [\fB-abciuVv\fR] [\fIposname\fR] \fIarchive\fR \fIfile\fR...
.fi

.LP
.nf
\fB/usr/xpg4/bin/ar\fR \fB-t\fR [\fB-sVv\fR] \fIarchive\fR [\fIfile\fR]...
.fi

.LP
.nf
\fB/usr/xpg4/bin/ar\fR \fB-x\fR [\fB-CsTVv\fR] \fIarchive\fR [\fIfile\fR]...
.fi

.SH DESCRIPTION
.sp
.LP
The \fBar\fR utility maintains groups of files combined into a single archive
file. Its main use is to create and update library files. However, it can be
used for any similar purpose. The magic string and the file headers used by
\fBar\fR consist of printable \fBASCII\fR characters. If an archive is composed
of printable files, the entire archive is printable.
.sp
.LP
When \fBar\fR creates an archive, it creates headers in a format that is
portable across all machines. The portable archive format and structure are
described in detail in \fBar.h\fR(3HEAD). The archive symbol table described
there is used by the link editor \fBld\fR(1) to effect multiple passes over
libraries of object files in an efficient manner. An archive symbol table is
only created and maintained by \fBar\fR when there is at least one object file
in the archive. The archive symbol table is in a specially named file that is
always the first file in the archive. This file is never mentioned or
accessible to the user. Whenever the \fBar\fR command is used to create or
update the contents of such an archive, the symbol table is rebuilt. The
\fB-s\fR option described below forces the symbol table to be rebuilt.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.RS 6n
Positions new \fIfile\fRs in \fIarchive\fR after the file named by the
\fIposname\fR operand.
.RE

.sp
.ne 2
.na
\fB\fB-b\fR\fR
.ad
.RS 6n
Positions new \fIfile\fRs in \fIarchive\fR before the file named by the
\fIposname\fR operand.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR\fR
.ad
.RS 6n
Suppresses the diagnostic message that is written to standard error by default
when \fIarchive\fR is created.
.RE

.sp
.ne 2
.na
\fB\fB-C\fR\fR
.ad
.RS 6n
Prevents extracted files from replacing like-named files in the file system.
This option is useful when \fB-T\fR is also used to prevent truncated file
names from replacing files with the same prefix.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR\fR
.ad
.RS 6n
Deletes one or more \fIfile\fRs from \fIarchive\fR.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR\fR
.ad
.RS 6n
Positions new \fIfile\fRs in \fIarchive\fR before the file named by the
\fIposname\fR operand. This option is quivalent to \fB-b\fR.
.RE

.sp
.ne 2
.na
\fB\fB-m\fR\fR
.ad
.RS 6n
Moves \fIfile\fRs. If \fB-a\fR, \fB-b\fR, or \fB-i\fR with the \fIposname\fR
operand are specified, the \fB-m\fR option moves \fIfile\fRs to the new
position. Otherwise, \fB-m\fR moves \fIfile\fRs to the end of \fIarchive\fR.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.RS 6n
Prints the contents of \fIfile\fRs in \fIarchive\fR to standard output. If no
\fIfile\fRs are specified, the contents of all files in \fIarchive\fR are
written in the order of the archive.
.RE

.sp
.ne 2
.na
\fB\fB-q\fR\fR
.ad
.RS 6n
Quickly appends \fIfile\fRs to the end of \fIarchive\fR. Positioning options
\fB-a\fR, \fB-b\fR, and \fB-i\fR are invalid. The command does not check
whether the added \fIfile\fRs are already in \fIarchive\fR. This option is
useful to avoid quadratic behavior when creating a large archive
piece-by-piece.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fR
.ad
.RS 6n
Replaces or adds \fIfile\fRs in \fIarchive\fR. If \fIarchive\fR does not exist,
a new archive file is created and a diagnostic message is written to standard
error, unless the \fB-c\fR option is specified. If no \fIfile\fRs are specified
and the \fIarchive\fR exists, the results are undefined. Files that replace
existing files do not change the order of the archive. If the \fB-u\fR option
is used with the \fB-r\fR option, only those files with dates of modification
later than the archive files are replaced. If the \fB-a\fR, \fB-b\fR, or
\fB-i\fR option is used, the \fIposname\fR argument must be present and
specifies that new files are to be placed after (\fB-a\fR) or before (\fB-b\fR
or \fB-i\fR) \fIposname\fR. Otherwise, the new files are placed at the end.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 6n
Forces the regeneration of the archive symbol table even if \fBar\fR is not
invoked with an option that will modify the archive contents. This command is
useful to restore the archive symbol table after the \fBstrip\fR(1) command has
been used on the archive.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR\fR
.ad
.RS 6n
Prints a table of contents of \fIarchive\fR. The files specified by the
\fIfile\fR operands are included in the written list. If no \fIfile\fR operands
are specified, all files in \fIarchive\fR are included in the order of the
archive.
.RE

.sp
.ne 2
.na
\fB\fB-T\fR\fR
.ad
.RS 6n
Allows file name truncation of extracted files whose archive names are longer
than the file system can support. By default, extracting a file with a name
that is too long is an error. In that case, a diagnostic message is written and
the file is not extracted.
.RE

.sp
.ne 2
.na
\fB\fB-u\fR\fR
.ad
.RS 6n
Updates older files. When used with the \fB-r\fR option, files within
\fIarchive\fR are replaced only if the corresponding \fIfile\fR has a
modification time that is at least as new as the modification time of the file
within \fIarchive\fR.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 6n
Gives verbose output. When used with options \fB-d\fR, \fB-r\fR, or \fB-x\fR,
the \fB-v\fR option writes a detailed file-by-file description of the archive
creation and the constituent \fIfile\fRs, and maintenance activity. When used
with \fB-p\fR, \fB-v\fR writes the name of the file to the standard output
before writing the file itself to the standard output. When used with \fB-t\fR,
\fB-v\fR includes a long listing of information about the files within the
archive. When used with \fB-x\fR, \fB-v\fR prints the filename preceding each
extraction. When writing to an archive, \fB-v\fR writes a message to the
standard error.
.RE

.sp
.ne 2
.na
\fB\fB-V\fR\fR
.ad
.RS 6n
Prints its version number on standard error.
.RE

.SS "\fB/usr/xpg4/bin/ar\fR"
.sp
.LP
The following options are supported for \fB/usr/xpg4/bin/ar\fR:
.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 6n
Same as the \fB/usr/bin/ar\fR version, except when writing to an archive, no
message is written to the standard error.
.RE

.sp
.ne 2
.na
\fB\fB-x\fR\fR
.ad
.RS 6n
Extracts the files named by the \fIfile\fR operands from \fIarchive\fR. The
contents of \fIarchive\fR are not changed. If no \fIfile\fR operands are given,
all files in \fIarchive\fR are extracted. If the file name of a file extracted
from \fIarchive\fR is longer than that supported in the directory to which it
is being extracted, the results are undefined. The modification time of each
\fIfile\fR extracted is set to the time \fIfile\fR is extracted from
\fIarchive\fR.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIarchive\fR\fR
.ad
.RS 11n
A path name of the archive file.
.RE

.sp
.ne 2
.na
\fB\fIfile\fR\fR
.ad
.RS 11n
A path name. Only the last component is used when comparing against the names
of files in the archive. If two or more \fIfile\fR operands have the same last
path name component (see \fBbasename\fR(1)), the results are unspecified. The
implementation's archive format will not truncate valid file names of files
added to or replaced in the archive.
.RE

.sp
.ne 2
.na
\fB\fIposname\fR\fR
.ad
.RS 11n
The name of a file in the archive file, used for relative positioning. See
options \fB-m\fR and \fB-r\fR.
.RE

.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBar\fR: \fBLANG\fR, \fBLC_ALL\fR,
\fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, \fBLC_TIME\fR, and \fBNLSPATH\fR.
.sp
.ne 2
.na
\fB\fBTMPDIR\fR\fR
.ad
.RS 10n
Determine the pathname that overrides the default directory for temporary
files, if any.
.RE

.sp
.ne 2
.na
\fB\fBTZ\fR\fR
.ad
.RS 10n
Determine the timezone used to calculate date and time strings written by
\fBar\fR \fB-tv\fR. If \fBTZ\fR is unset or null, an unspecified default
timezone is used.
.RE

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.SS "\fB/usr/bin/ar\fR"
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
.TE

.SS "\fB/usr/xpg4/bin/ar\fR"
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
Standard	See \fBstandards\fR(5).
.TE

.SH SEE ALSO
.sp
.LP
\fBbasename\fR(1), \fBcpio\fR(1), \fBld\fR(1), \fBlorder\fR(1), \fBstrip\fR(1),
\fBtar\fR(1), \fBar.h\fR(3HEAD), \fBa.out\fR(4), \fBattributes\fR(5),
\fBenviron\fR(5), \fBstandards\fR(5)
.SH NOTES
.sp
.LP
If the same file is mentioned twice in an argument list, it may be put in the
archive twice.
.sp
.LP
By convention, archives are suffixed with "\fB\&.a\fR".
.sp
.LP
When inserting \fBELF\fR objects into an archive file, \fBar\fR might add
"\fB\en\fR" characters to pad these objects to an 8-byte boundary. Such padding
improves the efficiency with which \fBld\fR(1) can access the archive. Only
\fBELF\fR object files are padded in this way. Other archive members are not
altered. When an object with such padding is extracted from an archive, the
padding is not included in the resulting output.