Provided by: manpages-posix_2017a-2_all 
PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of
this interface may differ (consult the corresponding Linux manual page for details of
Linux behavior), or the interface may not be implemented on Linux.
NAME
ar — create and maintain library archives
SYNOPSIS
ar -d [-v] archive file...
ar -m [-v] archive file...
ar -m -a [-v] posname archive file...
ar -m -b [-v] posname archive file...
ar -m -i [-v] posname archive file...
ar -p [-v] [-s] archive [file...]
ar -q [-cv] archive file...
ar -r [-cuv] archive file...
ar -r -a [-cuv] posname archive file...
ar -r -b [-cuv] posname archive file...
ar -r -i [-cuv] posname archive file...
ar -t [-v] [-s] archive [file...]
ar -x [-v] [-sCT] archive [file...]
DESCRIPTION
The ar utility is part of the Software Development Utilities option.
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.
OPTIONS
The ar utility shall conform to the Base Definitions volume of POSIX.1‐2017, Section 12.2,
Utility Syntax Guidelines, except for Guideline 9.
The following options shall be supported:
-a 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. Only 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.
OPERANDS
The following operands shall be supported:
archive A pathname of the archive.
file 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.
STDIN
Not used.
INPUT FILES
The archive named by archive shall be a file in the format created by ar -r.
ENVIRONMENT VARIABLES
The following environment variables shall affect the execution of ar:
LANG Provide a default value for the internationalization variables that are unset or
null. (See the Base Definitions volume of POSIX.1‐2017, 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.
ASYNCHRONOUS EVENTS
Default.
STDOUT
If the -d option is used with the -v option, the standard output format shall be:
"d - %s\n", <file>
where file is the operand specified on the command line.
If the -p option is used with the -v option, ar shall precede the contents of each file
with:
"\n<%s>\n\n", <file>
where file is the operand specified on the command line, if file operands were specified,
and the name of the file in the archive if they were not.
If the -r option is used with the -v option:
* If file is already in the archive, the standard output format shall be:
"r - %s\n", <file>
where <file> is the operand specified on the command line.
* If file is not already in the archive, the standard output format shall be:
"a - %s\n", <file>
where <file> is the operand specified on the command line.
If the -t option is used, ar shall write the names of the files in the archive to the
standard output in the format:
"%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.
If the -t option is used with the -v option, the standard output format shall be:
"%s %u/%u %u %s %d %d:%d %d %s\n", <member mode>, <user ID>,
<group ID>, <number of bytes in member>,
<abbreviated month>, <day-of-month>, <hour>,
<minute>, <year>, <file>
where:
<file> 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.
STDERR
The standard error shall be used only for diagnostic messages. The diagnostic message
about creating a new archive when -c is not specified shall not modify the exit status.
OUTPUT FILES
Archives are files with unspecified formats.
EXTENDED DESCRIPTION
None.
EXIT STATUS
The following exit values shall be returned:
0 Successful completion.
>0 An error occurred.
CONSEQUENCES OF ERRORS
Default.
The following sections are informative.
APPLICATION USAGE
None.
EXAMPLES
None.
RATIONALE
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 POSIX.1‐2017,
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
POSIX.1‐2017 makes the requirement explicit to avoid misunderstandings.
According to the System V documentation, the options -dmpqrtx are not required to begin
with a <hyphen-minus> ('-'). This volume of POSIX.1‐2017 requires that a conforming
application use the leading <hyphen-minus>.
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> characters. 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.
FUTURE DIRECTIONS
None.
SEE ALSO
c99, date, fort77, pax, strip
The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment Variables, Section
12.2, Utility Syntax Guidelines, <unistd.h>, description of {POSIX_NO_TRUNC}
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std
1003.1-2017, Standard for Information Technology -- Portable Operating System Interface
(POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 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 .
Any typographical or formatting errors that appear in this page are most likely to have
been introduced during the conversion of the source files to man page format. To report
such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .