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



PROLOG
       This  manual page is part of the POSIX Programmer's Man-
       ual.  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 Util-
       ities 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 main-
       tained 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 per-
       formed 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  IEEE Std 1003.1-2001,  Section 12.2, Utility
       Syntax Guidelines.

       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  file-
              names  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  stan-
              dard  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  cre-
              ating 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  ta-
              ble 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 stan-
              dard  output.   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 sys-
              tem  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 STD-
       OUT 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 rela-
              tive positioning; see options -m and -r.


STDIN
       Not used.

INPUT FILES
       The archive named by archive shall be a file in the for-
       mat created by ar -r.

ENVIRONMENT VARIABLES
       The  following  environment  variables  shall affect the
       execution of ar:

       LANG   Provide a default value for the internationaliza-
              tion  variables  that are unset or null. (See the
              Base Definitions volume of  IEEE Std 1003.1-2001,
              Section  8.2,  Internationalization Variables for
              the precedence of internationalization  variables
              used  to  determine  the  values  of locale cate-
              gories.)

       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 mes-
              sages 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 stan-
       dard 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  out-
          put 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  stan-
       dard 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 dif-
       ferent format and order of presentation of these  fields
       relative to each other may be used in a format appropri-
       ate in the specified locale.

       If the -x option is used with the -v option,  the  stan-
       dard 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 dupli-
       cation;  the ar utility is included to provide an inter-
       face 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  sup-
       posed  to  contain  a symbol table. As in this volume of
       IEEE Std 1003.1-2001, 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  implementa-
       tions do so, however, causing unexpected results for the
       application.     Therefore,     this      volume      of
       IEEE Std 1003.1-2001  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 IEEE Std 1003.1-2001 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  cre-
       ated  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>s.  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  applica-
       tions   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 his-
       torical 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  cur-
       rent  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 vol-
       ume  of  IEEE Std 1003.1-2001,  Chapter   13,   Headers,
       <unistd.h> description of {POSIX_NO_TRUNC}

COPYRIGHT
       Portions  of  this  text are reprinted and reproduced in
       electronic form from  IEEE  Std  1003.1,  2003  Edition,
       Standard  for Information Technology -- Portable Operat-
       ing System Interface (POSIX), The Open Group Base Speci-
       fications Issue 6, Copyright (C) 2001-2003 by the Insti-
       tute 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.open-
       group.org/unix/online.html .



IEEE/The Open Group                  2003                               AR(1P)
