NAME

ar − archive and library maintainer for portable archives

SYNOPSIS

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

DESCRIPTION

The ar command 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.  It can be used, though, for any similar purpose.  The magic string and the file headers used by ar consist of printable ASCII characters.  If an archive is composed 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 is described in detail in ar(4).  The archive symbol table (described in ar(4)) 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 symbol table is in a specially named file which 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 such an archive, the symbol table is rebuilt.  The s option described below will force the symbol table to be rebuilt. 

Key is an optional −, followed by one character from the set drqtpmxFSCQ, optionally concatenated with one or more of vuaibclsf.  Afile is the archive file.  The names are constituent files in the archive file.  The meanings of the key characters are:

d Delete the named files from the archive file. 

r Replace the named files in the archive file.  If the optional character u is used with r, then 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, 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 new files are placed at the end.

q Same as r. It is preserved for interface compatibility. 

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

p Print the named files in the archive. 

m Move the named files to the end of the archive.  If a positioning character is present, then the posname argument must be present and, as in r, specifies where the files are to be moved. 

x Extract the named files.  If no names are given, all files in the archive are extracted.  In neither case does x alter the archive file. 

F Convert the archive into a fast-updating archive.  This type of archive will be updated without using a temporary file, if possible. 

S Convert the archive into the old-style slow-updating archive. 

C Compress a fast-updating archive.  Fast-updating archives grow very large because deleted/replaced files are still present.  This rewrites the archive, removing files that are no longer accessible. 

Q Query an archive to find out if it is a fast-updating archive or a slow-updating archive. 

T Create an empty file for each file in the archive, setting its time and date to those stored in the archive.  This can be used for make file dependencies so space is not wasted by having both the object files and the archive file both always be present. 

v 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, give a long listing of all information about the files.  When used with x, precede each file with a name. 

c Suppress the message that is produced by default when afile is created. 

l No effect.  Provided for compatibility. 

s Force the regeneration of the archive symbol table even if ar(1) is not invoked with a command which 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. 

f Cause a command which updates the archive to write the new archive as a fast-updating archive. 

O Truncate long names to 14 characters like older link archivers did. 

FILES

.%%ar-<pid>%%         temporary file archive is written to. 
.%%ar-backup-<pid>%%  backup of archive while updating.

SEE ALSO

ld(1), lorder(1), strip(1). 
a.out(4), ar(4) in the CX/UX Programmer’s Reference Manual. 

BUGS

If the same file is mentioned twice in an argument list, it may be put in the archive twice.  This is a complete rewrite of the AT&T ar command.  It runs 5 to 20 times faster than the original.  Most of AT&T’s bugs have been carefully reproduced.

CX/UX User’s Reference Manual