ar(1p) — Linux manual page

PROLOG | NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | STDIN | INPUT FILES | ENVIRONMENT VARIABLES | ASYNCHRONOUS EVENTS | STDOUT | STDERR | OUTPUT FILES | EXTENDED DESCRIPTION | EXIT STATUS | CONSEQUENCES OF ERRORS | APPLICATION USAGE | EXAMPLES | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

AR(1P)                  POSIX Programmer's Manual                 AR(1P)

PROLOG         top

       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         top

       ar — create and maintain library archives

SYNOPSIS         top

       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         top

       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         top

       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         top

       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         top

       Not used.

INPUT FILES         top

       The archive named by archive shall be a file in the format
       created by ar -r.

ENVIRONMENT VARIABLES         top

       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         top

       Default.

STDOUT         top

       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         top

       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         top

       Archives are files with unspecified formats.

EXTENDED DESCRIPTION         top

       None.

EXIT STATUS         top

       The following exit values shall be returned:

        0    Successful completion.

       >0    An error occurred.

CONSEQUENCES OF ERRORS         top

       Default.

       The following sections are informative.

APPLICATION USAGE         top

       None.

EXAMPLES         top

       None.

RATIONALE         top

       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         top

       None.

SEE ALSO         top

       c99(1p), date(1p), fort77(1p), pax(1p), strip(1p)

       The Base Definitions volume of POSIX.1‐2017, Chapter 8,
       Environment Variables, Section 12.2, Utility Syntax Guidelines,
       unistd.h(0p), description of {POSIX_NO_TRUNC}

COPYRIGHT         top

       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 .

IEEE/The Open Group               2017                            AR(1P)

Pages that refer to this page: c99(1p)file(1p)fort77(1p)make(1p)nm(1p)strip(1p)