The ar
utility can be used to create and maintain groups of files
combined into an archive. Once an archive has been created,
new files can be added, and existing files in an archive can
be extracted, deleted, or replaced. When an archive consists
entirely of valid object files, the implementation shall
format the archive so that it is usable as a library for
link editing (see c99 and fort77). When some
of the archived files are not valid object files, the
suitability of the archive for library use is undefined.
If an archive consists entirely of printable files,
the entire archive shall be printable.

When ar
creates an archive, it creates administrative information
indicating whether a symbol table is present in the archive.
When there is at least one object file that ar
recognizes as such in the archive, an archive symbol table
shall be created in the archive and maintained by ar;
it is used by the link editor to search the archive.
Whenever the ar utility is used to create or update
the contents of such an archive, the symbol table shall be
rebuilt. The -s option shall force the symbol table
to be rebuilt.

All file
operands can be pathnames. However, files within archives
shall be named by a filename, which is the last component of
the pathname used when the file was entered into the
archive. The comparison of file operands to the names
of files in archives shall be performed by comparing the
last component of the operand to the name of the file in the
archive.

It is
unspecified whether multiple files in the archive may be
identically named. In the case of such files, however, each
file and posname operand shall match
only the first file in the archive having a name that is the
same as the last component of the operand.

Position new files in the archive after the file named
by the posname operand.

-b

Position new files in the archive before the file named
by the posname operand.

-c

Suppress the diagnostic message that is written to
standard error by default when the archive archive is
created.

-C

Prevent extracted files from replacing like-named files
in the file system. This option is useful when -T is
also used, to prevent truncated filenames from replacing
files with the same prefix.

-d

Delete one or more files from archive.

-i

Position new files in the archive before the file in the
archive named by the posname operand (equivalent to
-b).

-m

Move the named files in the archive. The -a,
-b, or -i options with the posname
operand indicate the position; otherwise, move the names
files in the archive to the end of the archive.

-p

Write the contents of the files in the archive
named by file operands from archive to the
standard output. If no file operands are specified,
the contents of all files in the archive shall be written in
the order of the archive.

-q

Append the named files to the end of the archive. In
this case ar does not check whether the added files
are already in the archive. This is useful to bypass the
searching otherwise done when creating a large archive piece
by piece.

-r

Replace or add files to archive. If the
archive named by archive does not exist, a new
archive shall be created and a diagnostic message shall be
written to standard error (unless the -c option is
specified). If no files are specified and the
archive exists, the results are undefined. Files that
replace existing files in the archive shall not change the
order of the archive. Files that do not replace existing
files in the archive shall be appended to the archive
unless a -a, -b, or -i option
specifies another position.

-s

Force the regeneration of the archive symbol table even
if ar is not invoked with an option that modifies the
archive contents. This option is useful to restore the
archive symbol table after it has been stripped; see
strip.

-t

Write a table of contents of archive to the
standard output. The files specified by the file
operands shall be included in the written list. If no
file operands are specified, all files in
archive shall be included in the order of the
archive.

-T

Allow filename 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
shall be an error; a diagnostic message shall be written and
the file shall not be extracted.

-u

Update older files in the archive. When used with the
-r option, files in the archive shall be replaced
only if the corresponding file has a modification
time that is at least as new as the modification time of the
file in the archive.

-v

Give verbose output. When used with the option
characters -d, -r, or -x, write a
detailed file-by-file description of the archive creation
and maintenance activity, as described in the STDOUT
section.

When used with
-p, write the name of the file in the archive to the
standard output before writing the file in the archive
itself to the standard output, as described in the STDOUT
section.

When used with
-t, include a long listing of information about the
files in the archive, as described in the STDOUT
section.

-x

Extract the files in the archive
named by the file operands from archive. The
contents of the archive shall not be changed. If no
file operands are given, all files in the archive
shall be extracted. The modification time of each file
extracted shall be set to the time the file is extracted
from the archive.

A pathname. Only the last component shall be used when
comparing against the names of files in the archive. If two
or more file operands have the same last pathname
component (basename), the results are unspecified. The
implementation’s archive format shall not truncate
valid filenames of files added to or replaced in the
archive.

posname

The name of a file in the
archive, used for relative positioning; see options
-m and -r.

Provide a default value for the internationalization
variables that are unset or null. (See the Base Definitions
volume of IEEE Std 1003.1-2001, Section 8.2,
Internationalization Variables for the precedence of
internationalization variables used to determine the values
of locale categories.)

LC_ALL

If set to a non-empty string value, override the values
of all the other internationalization variables.

LC_CTYPE

Determine the locale for the
interpretation of sequences of bytes of text data as
characters (for example, single-byte as opposed to
multi-byte characters in arguments and input files).

LC_MESSAGES

Determine the locale that
should be used to affect the format and contents of
diagnostic messages written to standard error.

LC_TIME

Determine the format and
content for date and time strings written by ar-tv.

NLSPATH

Determine the location of
message catalogs for the processing of LC_MESSAGES
.

TMPDIR

Determine the pathname that overrides the default
directory for temporary files, if any.

TZ

Determine the timezone used to calculate date and time
strings written by ar-tv. If TZ is
unset or null, an unspecified default timezone shall be
used.

Shall be the operand specified
on the command line, if file operands were specified,
or the name of the file in the archive if they were not.

<member mode>

Shall be
formatted the same as the <file mode>
string defined in the STDOUT section of ls, except
that the first character, the
<entry type>, is not used; the string
represents the file mode of the file in the archive at the
time it was added to or replaced in the archive.

The following
represent the last-modification time of a file when it was
most recently added to or replaced in the archive:
<abbreviated month>

Equivalent to
the format of the %b conversion specification format
in date.

<day-of-month>

Equivalent to
the format of the %e conversion specification format
in date.

<hour>

Equivalent to the format of the %H conversion
specification format in date.

<minute>

Equivalent to the format of the
%M conversion specification format in
date.

<year>

Equivalent to the format of the %Y conversion
specification format in date.

When
LC_TIME does not specify the POSIX locale, a
different format and order of presentation of these fields
relative to each other may be used in a format appropriate
in the specified locale.

If the
-x option is used with the -v option, the
standard output format shall be:

"x -
%s\n", <file>

where
file is the operand specified on the command line, if
file operands were specified, or the name of the file
in the archive if they were not.

The archive
format is not described. It is recognized that there are
several known ar formats, which are not compatible.
The ar utility is included, however, to allow
creation of archives that are intended for use only on one
machine. The archive is specified as a file, and it can be
moved as a file. This does allow an archive to be moved from
one machine to another machine that uses the same
implementation of ar.

Utilities such
as pax (and its forebears tar and cpio)
also provide portable "archives". This is a not a
duplication; the ar utility is included to provide an
interface primarily for make and the compilers, based
on a historical model.

In historical
implementations, the -q option (available on
XSI-conforming systems) is known to execute quickly because
ar does not check on whether the added members are
already in the archive. This is useful to bypass the
searching otherwise done when creating a large archive
piece-by-piece. These remarks may but need not remain true
for a brand new implementation of this utility; hence, these
remarks have been moved into the RATIONALE.

BSD
implementations historically required applications to
provide the -s option whenever the archive was
supposed to contain a symbol table. As in this volume of
IEEE Std 1003.1-2001, System V historically
creates or updates an archive symbol table whenever an
object file is removed from, added to, or updated in the
archive.

The OPERANDS
section requires what might seem to be true without
specifying it: the archive cannot truncate the filenames
below {NAME_MAX}. Some historical implementations do so,
however, causing unexpected results for the application.
Therefore, this volume of IEEE Std 1003.1-2001
makes the requirement explicit to avoid
misunderstandings.

According to
the System V documentation, the options -dmpqrtx are
not required to begin with a hyphen ( ’-’
). This volume of IEEE Std 1003.1-2001 requires
that a conforming application use the leading hyphen.

The archive
format used by the 4.4 BSD implementation is documented in
this RATIONALE as an example: A file created by ar
begins with the "magic" string
"!<arch>\n" . The rest of the archive
is made up of objects, each of which is composed of a header
for a file, a possible filename, and the file contents. The
header is portable between machine architectures, and, if
the file contents are printable, the archive is itself
printable.

The header is
made up of six ASCII fields, followed by a two-character
trailer. The fields are the object name (16 characters), the
file last modification time (12 characters), the user and
group IDs (each 6 characters), the file mode (8 characters),
and the file size (10 characters). All numeric fields are in
decimal, except for the file mode, which is in octal.

The
modification time is the file st_mtime field. The
user and group IDs are the file st_uid and
st_gid fields. The file mode is the file
st_mode field. The file size is the file
st_size field. The two-byte trailer is the string
"‘<newline>" .

Only the name
field has any provision for overflow. If any filename is
more than 16 characters in length or contains an embedded
space, the string "#1/" followed by the
ASCII length of the name is written in the name field. The
file size (stored in the archive header) is incremented by
the length of the name. The name is then written immediately
following the archive header.

Any unused
characters in any of these fields are written as
<space>s. If any fields are their particular maximum
number of characters in length, there is no separation
between the fields.

Objects in the
archive are always an even number of bytes long; files that
are an odd number of bytes long are padded with a
<newline>, although the size in the header does not
reflect this.

The ar
utility description requires that (when all its members are
valid object files) ar produce an object code
library, which the linkage editor can use to extract object
modules. If the linkage editor needs a symbol table to
permit random access to the archive, ar must provide
it; however, ar does not require a symbol table.

The BSD
-o option was omitted. It is a rare conforming
application that uses ar to extract object code from
a library with concern for its modification time, since this
can only be of importance to make. Hence, since this
functionality is not deemed important for applications
portability, the modification time of the extracted files is
set to the current time.

There is at
least one known implementation (for a small computer) that
can accommodate only object files for that system,
disallowing mixed object and other files. The ability to
handle any type of file is not only historical practice for
most implementations, but is also a reasonable
expectation.

Consideration
was given to changing the output format of ar-tv to the same format as the output of ls-l. This would have made parsing the output of
ar the same as that of ls. This was rejected
in part because the current ar format is commonly
used and changes would break historical usage. Second,
ar gives the user ID and group ID in numeric format
separated by a slash. Changing this to be the user name and
group name would not be correct if the archive were moved to
a machine that contained a different user database. Since
ar cannot know whether the archive was generated on
the same machine, it cannot tell what to report.

The text on the
-ur option combination is historical practice-since
one filename can easily represent two different files (for
example, /a/foo and /b/foo), it is reasonable
to replace the file in the archive even when the
modification time in the archive is identical to that in the
file system.

Portions of
this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information
Technology -- Portable Operating System Interface (POSIX),
The Open Group Base Specifications Issue 6, Copyright (C)
2001-2003 by the Institute of Electrical and Electronics
Engineers, Inc and The Open Group. In the event of any
discrepancy between this version 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 .