ar






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.


ar — create and maintain library archives



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...]

The utility is part of the Software Development Utilities
option.  The 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 and 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 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 recognizes as such in the archive, an archive
symbol table shall be created in the archive and maintained
by it is used by the link editor to search the archive.
Whenever the utility is used to create or update the
contents of such an archive, the symbol table shall be
rebuilt. The option shall force the symbol table to be
rebuilt.  All 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 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 and operand shall match only the first









                             ‐2‐


file in the archive having a name that is the same as the
last component of the operand.

The utility shall conform to the Base Definitions volume of
POSIX.1‐2008, except for Guideline 9.  The following options
shall be supported:

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

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

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

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

−d        Delete one or more from

−i        Position new files in the archive before the file
          in the archive named by the operand (equivalent to

−m        Move the named files in the archive. The or
          options with the operand indicate the position;
          otherwise, move the names files in the archive to
          the end of the archive.

−p        Write the contents of the in the archive named by
          operands from to the standard output. If no
          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 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 to If the archive named by does not
          exist, a new archive shall be created and a
          diagnostic message shall be written to standard
          error (unless the option is specified). If no are
          specified and the 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 or option specifies another position.









                             ‐3‐


−s        Force the regeneration of the archive symbol table
          even if 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

−t        Write a table of contents of to the standard
          output. Only the files specified by the operands
          shall be included in the written list. If no
          operands are specified, all files in 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 option, files in the archive shall be replaced
          only if the corresponding 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 or write a detailed file‐by‐file
          description of the archive creation and
          maintenance activity, as described in the STDOUT
          section.
                    When used with 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 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
          operands from The contents of the archive shall
          not be changed. If no 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.

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









                             ‐4‐


          archive. If two or more 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 and

Not used.

The archive named by shall be a file in the format created
by

The following environment variables shall affect the
execution of

LANG      Provide a default value for the
          internationalization variables that are unset or
          null. (See the Base Definitions volume of
          POSIX.1‐2008, 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

NLSPATH   Determine the location of message catalogs for the
          processing of

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 If is unset or null, an
          unspecified default timezone shall be used.













                             ‐5‐


Default.

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

          "d − %s\n", <file>
where is the operand specified on the command line.  If the
option is used with the option, shall precede the contents
of each file with:

          "\n<%s>\n\n", <file>
where is the operand specified on the command line, if
operands were specified, and the name of the file in the
archive if they were not.  If the option is used with the
option:

 *  If 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 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 option is used, shall write the names of the
    files in the archive to the standard output in the
    format:

        "%s\n", <file>
    where is the operand specified on the command line, if
    operands were specified, or the name of the file in the
    archive if they were not.  If the option is used with
    the 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 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 except
          that the first character, the <entry type>, is not
          used; the string represents the file mode of the









                             ‐6‐


          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 conversion
          specification format in

<day‐of‐month>
          Equivalent to the format of the conversion
          specification format in

<hour>    Equivalent to the format of the conversion
          specification format in

<minute>  Equivalent to the format of the conversion
          specification format in

<year>    Equivalent to the format of the conversion
          specification format in When 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 option is used with the
          option, the standard output format shall be:

                    "x − %s\n", <file>
          where is the operand specified on the command
          line, if operands were specified, or the name of
          the file in the archive if they were not.

The standard error shall be used only for diagnostic
messages.  The diagnostic message about creating a new
archive when is not specified shall not modify the exit
status.

Archives are files with unspecified formats.

None.

The following exit values shall be returned:

 0    Successful completion.

>0    An error occurred.

Default.














                             ‐7‐


None.

None.

The archive format is not described. It is recognized that
there are several known formats, which are not compatible.
The 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 Utilities such as (and its forebears and also provide
portable ‘‘archives’’. This is a not a duplication; the
utility is included to provide an interface primarily for
and the compilers, based on a historical model.  In
historical implementations, the option (available on XSI‐
conforming systems) is known to execute quickly because 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 option
whenever the archive was supposed to contain a symbol table.
As in this volume of POSIX.1‐2008, 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‐2008
makes the requirement explicit to avoid misunderstandings.
According to the System V documentation, the options are not
required to begin with a <hyphen> (This volume of
POSIX.1‐2008 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 begins with the ‘‘magic’’ string 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.









                             ‐8‐


     The modification time is the file field. The user and
     group IDs are the file and fields. The file mode is the
     file field. The file size is the file field. The two‐
     byte trailer is the string 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 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 utility description requires that (when all its members
are valid object files) 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, must provide it; however, does not
require a symbol table.  The BSD option was omitted. It is a
rare conforming application that uses to extract object code
from a library with concern for its modification time, since
this can only be of importance to 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 to the same format as the
output of This would have made parsing the output of the
same as that of This was rejected in part because the
current format is commonly used and changes would break
historical usage.  Second, 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 cannot know whether the archive was
generated on the same machine, it cannot tell what to
report.  The text on the option combination is historical
practice—since one filename can easily represent two
different files (for example, and 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.













                             ‐9‐


None.

The Base Definitions volume of POSIX.1‐2008, description of
{POSIX_NO_TRUNC}

Portions of this text are reprinted and reproduced in
electronic form from IEEE Std 1003.1, 2013 Edition, Standard
for Information Technology ‐‐ Portable Operating System
Interface (POSIX), The Open Group Base Specifications Issue
7, Copyright (C) 2013 by the Institute of Electrical and
Electronics Engineers, Inc and The Open Group.  (This is
POSIX.1‐2008 with the 2013 Technical Corrigendum 1 applied.)
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.unix.org/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 .