Provided by: manpages-posix_2017a-2_all bug

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 .