xenial (1) ar.1posix.gz

Provided by: manpages-posix_2013a-1_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‐2008, 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‐2008, 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‐2008, System V historically creates or
       updates an archive symbol table whenever an object file is removed from, added  to,  or  updated  in  the
       archive.

       The  OPERANDS  section  requires  what  might  seem  to be true without specifying it: the archive cannot
       truncate the filenames below  {NAME_MAX}.   Some  historical  implementations  do  so,  however,  causing
       unexpected  results  for  the  application.  Therefore, this volume of POSIX.1‐2008 makes the requirement
       explicit to avoid misunderstandings.

       According to the System V documentation, the options −dmpqrtx are not required to begin with  a  <hyphen>
       ('−').  This volume of POSIX.1‐2008 requires that a conforming application use the leading <hyphen>.

       The archive format used by the 4.4 BSD implementation is documented in this RATIONALE as an example:

              A  file  created  by  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‐2008, Chapter 8, Environment Variables, Section 12.2, Utility
       Syntax Guidelines, <unistd.h>, description of {POSIX_NO_TRUNC}

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2013 Edition,
       Standard  for  Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electrical and Electronics Engineers,  Inc
       and  The  Open Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the event
       of any discrepancy between this version and the original IEEE and The Open Group Standard,  the  original
       IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at
       http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are most likely to have  been  introduced
       during   the   conversion  of  the  source  files  to  man  page  format.  To  report  such  errors,  see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .