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 XBD Utility Syntax Guidelines, except for 
Guideline 9.

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 (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 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 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. Only 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 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. 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. When used with -t, include
        a long listing of information about the files in the archive.

-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.
