Man Pages

ar(1p) - phpMan ar(1p) - phpMan

Command: man perldoc info search(apropos)  


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 dif-
       fer (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 IEEE Std 1003.1-2001, Section 12.2, Utility Syn-
       tax 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 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  (equiva-
              lent 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  out-
              put.   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  exist-
              ing  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 modi-
              fies 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 mes-
              sage 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 IEEE Std 1003.1-2001, Section 8.2, Internationalization Variables for the prece-
              dence 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 exam-
              ple, 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  writ-
              ten 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 dupli-
       cation; 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  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 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  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 maxi-
       mum 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  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  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  dif-
       ferent  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, Stan-
       dard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base  Specifica-
       tions  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 Stan-
       dard,  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)