AR(1P) - phpMan

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

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  com-
       bined  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  ar-
       chive 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 indi-
       cating  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  path-
       name 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  identi-
       cally 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 pre-
              vent truncated filenames from replacing files with the same pre-
              fix.
       -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 op-
              erands 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 ar-
              chive. 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.
              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 mod-
              ification 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 ar-
              chive 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 position-
              ing; 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
              IEEE Std 1003.1-2001,  Section  8.2,  Internationalization Vari-
              ables 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 writ-
              ten 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 con-
       tents of each file with:

              "\n<%s>\n\n", <file>
       where file is the operand specified on the command line, if file  oper-
       ands  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 oper-
       ands 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  op-
              erands 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 for-
              mat in date.
       <day-of-month>
              Equivalent to the format of the %e conversion specification for-
              mat in date.
       <hour> Equivalent to the format of the %H conversion specification for-
              mat in date.
       <minute>
              Equivalent to the format of the %M conversion specification for-
              mat in date.
       <year> Equivalent to the format of the %Y conversion specification for-
              mat 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 oper-
       ands 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  speci-
       fied 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-conform-
       ing 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 IEEE Std 1003.1-2001, System V historically cre-
       ates 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 speci-
       fying 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
       IEEE Std 1003.1-2001  makes the requirement explicit to avoid misunder-
       standings.
       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 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 char-
       acters), the file mode (8 characters), and the file  size  (10  charac-
       ters).  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 follow-
       ing 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 link-
       age 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 mod-
       ification 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  rea-
       sonable 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 histori-
       cal  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 con-
       tained a different user database. Since ar cannot know whether the  ar-
       chive 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
       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  Operating  System  Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003  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 .

IEEE/The Open Group                  2003                               AR(1P)