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



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       ar -- create and maintain library archives

SSYYNNOOPPSSIISS
       ar -d [[-v]] _a_r_c_h_i_v_e _f_i_l_e...

       ar -m [[-v]] _a_r_c_h_i_v_e _f_i_l_e...
       ar -m -a [[-v]] _p_o_s_n_a_m_e _a_r_c_h_i_v_e _f_i_l_e...
       ar -m -b [[-v]] _p_o_s_n_a_m_e _a_r_c_h_i_v_e _f_i_l_e...
       ar -m -i [[-v]] _p_o_s_n_a_m_e _a_r_c_h_i_v_e _f_i_l_e...

       ar -p [[-v]] [[-s]] _a_r_c_h_i_v_e [[_f_i_l_e...]]

       ar -q [[-cv]] _a_r_c_h_i_v_e _f_i_l_e...

       ar -r [[-cuv]] _a_r_c_h_i_v_e _f_i_l_e...

       ar -r -a [[-cuv]] _p_o_s_n_a_m_e _a_r_c_h_i_v_e _f_i_l_e...
       ar -r -b [[-cuv]] _p_o_s_n_a_m_e _a_r_c_h_i_v_e _f_i_l_e...
       ar -r -i [[-cuv]] _p_o_s_n_a_m_e _a_r_c_h_i_v_e _f_i_l_e...

       ar -t [[-v]] [[-s]] _a_r_c_h_i_v_e [[_f_i_l_e...]]

       ar -x [[-v]] [[-sCT]] _a_r_c_h_i_v_e [[_f_i_l_e...]]

DDEESSCCRRIIPPTTIIOONN
       The _a_r utility is part of the Software Development Utilities option.

       The _a_r 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 _c_9_9 and _f_o_r_t_7_7).  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 _a_r 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 _a_r recognizes as such in the archive,
       an archive symbol table shall be created in the archive and maintained
       by _a_r; it is used by the link editor to search the archive. Whenever
       the _a_r utility is used to create or update the contents of such an
       archive, the symbol table shall be rebuilt. The --ss option shall force
       the symbol table to be rebuilt.

       All _f_i_l_e 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 _f_i_l_e 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 _f_i_l_e and
       _p_o_s_n_a_m_e operand shall match only the first file in the archive having a
       name that is the same as the last component of the operand.

OOPPTTIIOONNSS
       The _a_r utility shall conform to the Base Definitions volume of
       POSIX.1-2017, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s, except for
       Guideline 9.

       The following options shall be supported:

       --aa        Position new files in the archive after the file named by the
                 _p_o_s_n_a_m_e operand.

       --bb        Position new files in the archive before the file named by
                 the _p_o_s_n_a_m_e operand.

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

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

       --dd        Delete one or more _f_i_l_es from _a_r_c_h_i_v_e.

       --ii        Position new files in the archive before the file in the
                 archive named by the _p_o_s_n_a_m_e operand (equivalent to --bb).

       --mm        Move the named files in the archive. The --aa, --bb, or --ii
                 options with the _p_o_s_n_a_m_e operand indicate the position;
                 otherwise, move the names files in the archive to the end of
                 the archive.

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

       --qq        Append the named files to the end of the archive. In this
                 case _a_r 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.

       --rr        Replace or add _f_i_l_es to _a_r_c_h_i_v_e.  If the archive named by
                 _a_r_c_h_i_v_e does not exist, a new archive shall be created and a
                 diagnostic message shall be written to standard error (unless
                 the --cc option is specified). If no _f_i_l_es are specified and
                 the _a_r_c_h_i_v_e 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 --aa, --bb, or --ii option specifies another position.

       --ss        Force the regeneration of the archive symbol table even if _a_r
                 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 _s_t_r_i_p.

       --tt        Write a table of contents of _a_r_c_h_i_v_e to the standard output.
                 Only the files specified by the _f_i_l_e operands shall be
                 included in the written list. If no _f_i_l_e operands are
                 specified, all files in _a_r_c_h_i_v_e shall be included in the
                 order of the archive.

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

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

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

                 When used with --pp, 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 --tt, include a long listing of information
                 about the files in the archive, as described in the STDOUT
                 section.

       --xx        Extract the files in the archive named by the _f_i_l_e operands
                 from _a_r_c_h_i_v_e.  The contents of the archive shall not be
                 changed. If no _f_i_l_e 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.

OOPPEERRAANNDDSS
       The following operands shall be supported:

       _a_r_c_h_i_v_e   A pathname of the archive.

       _f_i_l_e      A pathname. Only the last component shall be used when
                 comparing against the names of files in the archive. If two
                 or more _f_i_l_e 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.

       _p_o_s_n_a_m_e   The name of a file in the archive, used for relative
                 positioning; see options --mm and --rr.

SSTTDDIINN
       Not used.

IINNPPUUTT FFIILLEESS
       The archive named by _a_r_c_h_i_v_e shall be a file in the format created by
       _a_r --rr.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of _a_r:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

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

       _L_C___C_T_Y_P_E  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).

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

       _L_C___T_I_M_E   Determine the format and content for date and time strings
                 written by _a_r --ttvv.

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

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

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

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
       If the --dd option is used with the --vv option, the standard output format
       shall be:


           "d - %s\n", <_f_i_l_e>

       where _f_i_l_e is the operand specified on the command line.

       If the --pp option is used with the --vv option, _a_r shall precede the
       contents of each file with:


           "\n<%s>\n\n", <_f_i_l_e>

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

       If the --rr option is used with the --vv option:

        *  If _f_i_l_e is already in the archive, the standard output format shall
           be:


               "r - %s\n", <_f_i_l_e>

           where <_f_i_l_e> is the operand specified on the command line.

        *  If _f_i_l_e is not already in the archive, the standard output format
           shall be:


               "a - %s\n", <_f_i_l_e>

           where <_f_i_l_e> is the operand specified on the command line.

       If the --tt option is used, _a_r shall write the names of the files in the
       archive to the standard output in the format:


           "%s\n", <_f_i_l_e>

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

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


           "%s %u/%u %u %s %d %d:%d %d %s\n", <_m_e_m_b_e_r _m_o_d_e>, <_u_s_e_r _I_D>,
               <_g_r_o_u_p _I_D>, <_n_u_m_b_e_r _o_f _b_y_t_e_s _i_n _m_e_m_b_e_r>,
               <_a_b_b_r_e_v_i_a_t_e_d _m_o_n_t_h>, <_d_a_y_-_o_f_-_m_o_n_t_h>, <_h_o_u_r>,
               <_m_i_n_u_t_e>, <_y_e_a_r>, <_f_i_l_e>

       where:

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

       <_m_e_m_b_e_r _m_o_d_e>
                 Shall be formatted the same as the <_f_i_l_e _m_o_d_e> string defined
                 in the STDOUT section of _l_s, except that the first character,
                 the <_e_n_t_r_y _t_y_p_e>, 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:

       <_a_b_b_r_e_v_i_a_t_e_d _m_o_n_t_h>
                 Equivalent to the format of the %%bb conversion specification
                 format in _d_a_t_e.

       <_d_a_y_-_o_f_-_m_o_n_t_h>
                 Equivalent to the format of the %%ee conversion specification
                 format in _d_a_t_e.

       <_h_o_u_r>    Equivalent to the format of the %%HH conversion specification
                 format in _d_a_t_e.

       <_m_i_n_u_t_e>  Equivalent to the format of the %%MM conversion specification
                 format in _d_a_t_e.

       <_y_e_a_r>    Equivalent to the format of the %%YY conversion specification
                 format in _d_a_t_e.

       When _L_C___T_I_M_E 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 --xx option is used with the --vv option, the standard output format
       shall be:


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

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

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

OOUUTTPPUUTT FFIILLEESS
       Archives are files with unspecified formats.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       None.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    Successful completion.

       >0    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

EEXXAAMMPPLLEESS
       None.

RRAATTIIOONNAALLEE
       The archive format is not described. It is recognized that there are
       several known _a_r formats, which are not compatible. The _a_r 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 _a_r.

       Utilities such as _p_a_x (and its forebears _t_a_r and _c_p_i_o) also provide
       portable ``archives''. This is a not a duplication; the _a_r utility is
       included to provide an interface primarily for _m_a_k_e and the compilers,
       based on a historical model.

       In historical implementations, the --qq option (available on XSI-
       conforming systems) is known to execute quickly because _a_r 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
       --ss 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 --ddmmppqqrrttxx 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 _a_r begins with the ``magic'' string
              ""!!<<aarrcchh>>\\nn"".  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 _s_t___m_t_i_m_e field. The user and
              group IDs are the file _s_t___u_i_d and _s_t___g_i_d fields. The file mode
              is the file _s_t___m_o_d_e field. The file size is the file _s_t___s_i_z_e
              field. The two-byte trailer is the string ""``<<nneewwlliinnee>>"".

              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 ""##11//"" 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 _a_r utility description requires that (when all its members are
       valid object files) _a_r 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, _a_r must
       provide it; however, _a_r does not require a symbol table.

       The BSD --oo option was omitted. It is a rare conforming application that
       uses _a_r to extract object code from a library with concern for its
       modification time, since this can only be of importance to _m_a_k_e.
       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 _a_r --ttvv to the
       same format as the output of _l_s --ll.  This would have made parsing the
       output of _a_r the same as that of _l_s.  This was rejected in part because
       the current _a_r format is commonly used and changes would break
       historical usage.  Second, _a_r 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 _a_r cannot know whether
       the archive was generated on the same machine, it cannot tell what to
       report.

       The text on the --uurr option combination is historical practice--since
       one filename can easily represent two different files (for example,
       //aa//ffoooo and //bb//ffoooo), 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.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _c_9_9, _d_a_t_e, _f_o_r_t_7_7, _p_a_x, _s_t_r_i_p

       The Base Definitions volume of POSIX.1-2017, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t
       _V_a_r_i_a_b_l_e_s, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s, <<uunniissttdd..hh>>,
       description of {POSIX_NO_TRUNC}

CCOOPPYYRRIIGGHHTT
       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(1)
