Unix/Linux Go Back    


Linux 2.6 - man page for ar (linux section 1posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

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 ar-
       chive. 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,  Sec-
       tion 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 filenames from replac-
	      ing 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  pos-
	      name operand (equivalent to -b).

       -m     Move the named files in the archive. The -a, -b, or -i options with the posname op-
	      erand 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 ar-
	      chive 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 exist-
	      ing 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  ar-
	      chive 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 con-
	      tents 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 ar-
	      chive.

       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, Inter-
	      nationalization 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  interna-
	      tionalization 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  argu-
	      ments and input files).

       LC_MESSAGES
	      Determine the locale that should be used to affect the format and contents of diag-
	      nostic 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  speci-
	      fied, 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 presenta-
       tion 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 for-
       mats, 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 creat-
       ing 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 RATIO-
       NALE.

       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 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 ar-
       chive 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 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 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 architec-
       tures, 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  char-
       acters  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 num-
       ber  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 mod-
       ules.  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 appli-
       cations 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 sepa-
       rated 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 eas-
       ily 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 identi-
       cal 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					    AR(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 04:29 AM.