# ar

## 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 _file_ s 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 _file_ s 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 _file_ s 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 _file_ s 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.
    


* * *