ar(1)




NAME

     ar - maintain portable archive or library


SYNOPSIS

     /usr/ccs/bin/ar -d [-Vv] archive file...

     /usr/ccs/bin/ar -m [-abiVv] [posname] archive file...

     /usr/ccs/bin/ar -p [-sVv] archive [file...]

     /usr/ccs/bin/ar -q [-cVv] archive file...

     /usr/ccs/bin/ar -r [-abciuVv] [posname] archive file...

     /usr/ccs/bin/ar -t [-sVv] archive [file...]

     /usr/ccs/bin/ar -x [-CsTVv] archive [file...]

     /usr/xpg4/bin/ar -d [-Vv] archive file...

     /usr/xpg4/bin/ar -m [-abiVv] [posname] archive file...

     /usr/xpg4/bin/ar -p [-sVv] archive [file...]

     /usr/xpg4/bin/ar -q [-cVv] archive file...

     /usr/xpg4/bin/ar -r [-abciuVv] [posname] archive file...

     /usr/xpg4/bin/ar -t [-sVv] archive [file...]

     /usr/xpg4/bin/ar -x [-CsTVv] archive [file...]


DESCRIPTION

     The ar utility maintains groups of  files  combined  into  a
     single  archive  file.  Its main use is to create and update
     library files. However, it can be used for any similar  pur-
     pose.  The magic string and the file headers used by ar con-
     sist of printable ASCII characters. If an  archive  is  com-
     posed of printable files, the entire archive is printable.

     When ar creates an archive, it creates headers in  a  format
     that  is portable across all machines.  The portable archive
     format and structure are described in detail  in  ar(3HEAD).
     The archive symbol table (described in ar(3HEAD)) is used by
     the  link  editor  ld(1)  to  effect  multiple  passes  over
     libraries of object files in an efficient manner. An archive
     symbol table is only created and maintained by ar when there
     is at least one object file in the archive. The archive sym-
     bol table is in a specially named file that  is  always  the
     first  file  in the archive. This file is never mentioned or
     accessible to the user. Whenever the ar command is  used  to
     create or update the contents of such an archive, the symbol
     table is rebuilt. The -s option described below  will  force
     the symbol table to be rebuilt.


OPTIONS

     The following options are supported:

     -a    Positions new files in archive after the file named by
           the posname operand.

     -b    Positions new files in archive before the  file  named
           by the posname operand.

     -c    Suppresses the diagnostic message that is  written  to
           standard error by default when archive is created.

     -C    Prevents 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    Deletes one or more files from archive.

     -i    Positions new files in archive before the  file  named
           by the posname operand (equivalent to -b).

     -m    Moves files. If -a, -b, or -i with the posname operand
           are specified, moves files to the new position; other-
           wise, moves files to the end of archive.

     -p    Prints the contents of files in  archive  to  standard
           output. If no files are specified, the contents of all
           files in archive will be written in the order  of  the
           archive.

     -q    Quickly appends files to the end of archive. Position-
           ing  options  -a,  -b, and -i are invalid. The command
           does not check whether the added files are already  in
           archive.  This  option  is  useful  to avoid quadratic
           behavior when creating a large archive piece-by-piece.

     -r    Replaces or adds files in archive. If archive does not
           exist,  a new archive file will be created and a diag-
           nostic message  will  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 will not
           change the order of the archive. If the -u  option  is
           used  with  the  -r option, then only those files with
           dates of modification later than the archive files are
           replaced.  If  the  -a, -b, or -i option is used, then
           the posname argument must  be  present  and  specifies
           that  new  files are to be placed after (-a) or before
           (-b or -i) posname; otherwise the new files are placed
           at the end.

     -s    Forces the regeneration of the  archive  symbol  table
           even  if  ar  is  not invoked with an option that will
           modify the archive contents. This command is useful to
           restore  the  archive  symbol table after the strip(1)
           command has been used on the archive.

     -t    Prints a table  of  contents  of  archive.  The  files
           specified by the file operands will be included in the
           written list. If no file operands are  specified,  all
           files  in archive will be included in the order of the
           archive.

     -T    Allows file name truncation of extracted  files  whose
           archive names are longer than the file system can sup-
           port. By default, extracting a file with a  name  that
           is  too long is an error; a diagnostic message will be
           written and the file will not be extracted.

     -u    Updates older files.  When used with  the  -r  option,
           files  within  archive  will  be  replaced only if the
           corresponding file has a modification time that is  at
           least  as  new  as  the  modification time of the file
           within archive.

     -V    Prints its version number on standard error.

  /usr/ccs/bin/ar
     -v    Gives verbose output. When used with the option  char-
           acters  -d,  -r, or -x, writes a detailed file-by-file
           description of the archive creation  and  the  consti-
           tuent  files, and maintenance activity. When used with
           -p, writes the name of the file to the standard output
           before writing the file itself to the standard output.
           When used with -t, includes a long listing of informa-
           tion  about  the  files  within the archive. When used
           with -x, prints the filename  preceding  each  extrac-
           tion. When writing to an archive, a message is written
           to the standard error.

  /usr/xpg4/bin/ar
     -v    Same as /usr/ccs/bin/ar version, except  when  writing
           to  an  archive, no message is written to the standard
           error.

     -x    Extracts the files named by  the  file  operands  from
           archive.  The contents of archive will not be changed.
           If no file operands are given, all  files  in  archive
           will  be  extracted.  If  the  file  name  of  a  file
           extracted from archive is longer than  that  supported
           in  the  directory to which it is being extracted, the
           results are undefined. The modification time  of  each
           file  extracted  will  be  set  to  the  time  file is
           extracted from archive.


OPERANDS

     The following operands are supported:

     archive
           A path name of the archive file.

     file  A path name. Only the last component will be used when
           comparing  against  the names of files in the archive.
           If two or more file operands have the same  last  path
           name   component   (  basename(1)),  the  results  are
           unspecified. The implementation's archive format  will
           not  truncate  valid  file  names of files added to or
           replaced in the archive.

     posname
           The name of a file in the archive file, used for rela-
           tive positioning; see options -m and -r.


ENVIRONMENT VARIABLES

     See environ(5) for descriptions of the following environment
     variables  that  affect  the  execution of ar: LANG, LC_ALL,
     LC_CTYPE, LC_MESSAGES, LC_TIME, and NLSPATH.

     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.


EXIT STATUS

     The following exit values are returned:

     0     Successful completion.

     >0    An error occurred.


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

  /usr/ccs/bin/ar

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWbtool                   |
    |_____________________________|_____________________________|

  /usr/xpg4/bin/ar
     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWxcu4                    |
    |_____________________________|_____________________________|
    | Interface Stability         | Standard                    |
    |_____________________________|_____________________________|


SEE ALSO

     basename(1), cc(1B), cpio(1),  ld(1),  lorder(1),  strip(1),
     tar(1),   ar(3HEAD),  a.out(4),  attributes(5),  environ(5),
     standards(5)


NOTES

     If the same file is mentioned twice in an argument list,  it
     may be put in the archive twice.

     By convention, archives are suffixed with the characters .a.


Man(1) output converted with man2html