NAME

ar − maintain portable archives and libraries

SYNOPSIS

ar key [ posname ] afile [ name ] ... 

DESCRIPTION

Ar maintains groups of files combined into a single archive file.  Its main use is to create and update library files as used by the link editor (see ld(1). It can be used, however, for any similar purpose. The magic string and file headers used by ar consist of printable ASCII characters.  If an archive is composed of printable files, the entire archive is printable. 

Individual files are inserted without conversion into the archive file.  When ar creates an archive, it creates headers in a format that is portable across all machines.  The portable archive format and structure is described in detail in ar(4). The archive symbol table (described in ar(4)) is used by the link editor (ld(1)) to search repeatedly and efficiently through libraries of object files. An archive symbol table is created and maintained by ar only when the archive contains at least one object file.  The archive symbol 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(1) command is used to create or update the contents of an archive, the symbol table is rebuilt.  The s modifier described below forces the symbol table to be rebuilt. 

Key must be present, and consists of an optional −, followed by one operation character from the set drqtpmx, optionally concatenated with one or more modifier characters from the set vuaibcls.  Afile is the archive file.  Constituent files in the archive file are specified by name arguments. 

The TMPDIR environment variable can be set to specify a directory for temporary files (see tmpnam(3S)). TMPDIR overrides the default directory /usr/tmp as well as any use of the l modifier. 

The following key operation characters are recognized:

d Delete the named files from the archive file. 

r Replace the named files, or add a new file to the archive.  If the modifier u is used with the operation character r, only those files with dates of modification later than the archive files are replaced.  If an optional positioning character from the set abi is used, the posname argument must be present and specifies that new files are to be placed after (a) or before (b or i) posname. In the absence of a positioning character, new files are placed at the end. Ar creates afile if it does not already exist.  If no files are specified by name arguments, ar creates an empty archive file containing only the archive header (see ar(4)). 

q Quickly append the named files to the end of the archive file.  Positioning characters are invalid.  The operation does not check to determine whether the added members are already in the archive.  This is useful only to avoid quadratic behavior when creating a large archive piece-by-piece.  Ar creates afile if it does not already exist. 

t Print a table of contents of the archive file.  If no names are given, all files in the archive are described.  If names are given, information about only those files appears. 

p Print the named files in the archive. 

m Move the named files.  By default, the files are moved to the end of the archive.  If a positioning character is present, the posname argument must be present and, as in r, posname specifies where the files are to be moved.  Note that, when used with a positioning character, the files are moved in the same order that they currently appear in the archive, not in the order specified on the command line.  See EXAMPLES. 

x Extract the named files.  If no names are given, all files in the archive are extracted.  In neither case does x alter (that is, delete entries from) the archive file.  The following optional modifiers are recognized:

s Force the regeneration of the archive symbol table even if ar(1) is not invoked with an operation that modifies the archive contents.  This modifier is useful to restore the archive symbol table after the strip(1) command has been used on the archive. 

v Verbose.  Give a verbose file-by-file description of the making of a new archive file from the old archive and the constituent files.  When used with t, v gives a long listing of all information about the files.  When used with the d, m, p, q, and x operations, the verbose modifier causes ar to print each key operation character and file name associated with that operation.  For the r operation, ar shows an "a" if it adds a new file or an "r" if it replaces an existing one. 

c Create.  Normally ar creates afile if it does not already exist (for the r and q operations).  The c modifier suppresses the message normally produced when afile is created. 

l Local.  Place temporary files in the local current working directory, rather than in the default directory /usr/tmp.  Only the d, m, r and s modifiers use temporary files.  The TMPDIR environment variable overrides use of the l modifier. 

Only the following combinations are meaningful; no other combination of modifiers with operations have any effect on the operation:

d: v, l

r: u, v, c, l, and a | b | i

q: v, c

t: v, s

p: v, s

m: v, l, and a | b | i

x: v, s

DIAGNOSTICS

phase error on file name
The named file was modified by another process while ar was copying it into the archive.  When this happens, ar exits and the original archive is left untouched. 

ar write error:  file system error message
Ar could not write to a temporary file or the final output file.  If ar was trying to write the final output file, the original archive will be lost. 

Ar reports cannot create file.a, where file.a is an ar-format archive file, even if file.a already exists.  This message is triggered when file.a is write-protected or inaccessible. 

EXAMPLES

The command:

ar r newlib.a f3 f2 f1 f4

will create a new file (if one does not already exist) in archive format with its constituents entered in the order shown in the above command line. 

If you want to replace files f2 and f3 such that the new copies follow file f1 and f3 follows f2, the commands:

ar ma f1 newlib.a f2 f3
ar ma f2 newlib.a f3
ar r newlib.a f2 f3

will produce the desired effect.  The archive will now be ordered:

newlib.a:  f1 f2´ f3´ f4

where the single quote marks indicate updated files.  The first command says "move f2 and f3 after f1 in newlib.a", thus creating the order:

f1 f3 f2 f4

Note that the relative order of f2 and f3 has not changed.  The second command says "move f2 after f3 in newlib.a", creating the order:

f1 f2 f3 f4

The third command then replaces the files f2 and f3.  Since the files f2 and f3 both already existed in the archive, this sequence of commands could not be simply replaced by:

ar ra f1 newlib.a f2 f3

because the previous position and relative order of f2 and f3 in the archive will be preserved (no matter how the files are specified on the command line), producing the following archive:

newlib.a:  f3´ f2´ f1 f4

WARNINGS

If you are the super-user, ar will alter any archive file, even if it is write-protected. 

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

FILES

/usr/tmp/ar∗ temporary files

SEE ALSO

ld(1), lorder(1), strip(1), tmpnam(3S), a.out(4), ar(4). 

INTERNATIONAL SUPPORT

8- and 16-bit data, 8-bit file names. 

Hewlett-Packard Company  —  May 11, 2021