DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

ar(CP)


ar -- archive and library maintainer for portable archives

Syntax

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

Description

The ar(CP) command combines groups of files in a single archive file. Its primary use is to create and update linker library files, but it can be used for any similar purpose.

Unlike command options, the key is a required part of ar's command line. The key (which can begin with a "-") is formed with one of the following letters: dmpqrtx. Arguments to the key are optional and are made with one or more of the following: abcilsuv. posname is an archive member name used as a reference point in positioning other files in afile, the archive file. The names are constituent files in the archive file.

ar's magic string and the file headers consist of printable ASCII characters, so if an archive is composed of printable files, the entire archive can be printed. Archives of text files created by ar are portable between implementations of System V.

The portable archive format and structure is described in detail in the ar(FP) manual page. The archive symbol table is used by ld(CP) to effect multiple passes over libraries of object files.

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 that is always the first file in the archive (this file is not accessible to the user). Whenever ar is used to create or update the contents of an archive, the symbol table is rebuilt.

The long filename map is the second file in the archive (this file only exists if one or more archived files have long filenames). Previously, the ar format permitted archive members to have file names of up to 14 characters in length. Now longer file names are allowed. Thus, ar was changed to permit archiving files with such long names. In order to accommodate the longer file names without breaking backwards compatibility, another specially-named archive member, the long filename map, was introduced.

The long filename map comes right after the symbol table if any of the archived files have names longer than 14 characters. This means that both the symbol table and the longfilename map are optional, but when they both appear the longfilename map appears after the symbol table. The longfilename map contains a one-to-one mapping between the real filenames and coded files names that are used internally by ar. These coded names are not accessible by the user.

Valid key characters

Unlike command options, the key, which can begin with a "-", is a required part of ar's command line. The valid key is formed with one of the following letters: dmpqrtx.


d
Delete the named files from the archive file.

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

p
Print the named files in the archive.

q
Quickly append the named files to the end of the archive file. Optional positioning characters are invalid. The command does not check whether the added members are already in the archive. This option is useful to avoid quadratic behavior when creating a large archive piece-by-piece. Unchecked, the file can grow exponentially up to the second degree.

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 specify that new files are to be placed after (a) or before (b or i) posname. Otherwise new files are placed at the end.

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.

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.

Valid keyarg characters

Arguments to the key are made with one or more of the characters from the set [abcilsuv]. The meanings for keyarg are as described below.


a
A positioning character used with the m or r key characters. It specifies that new files are to be placed after posname in the archive file.

b
A positioning character used with the m or r key characters. It specifies that new files are to be placed before posname in the archive file.

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

i
A positioning character used with the m or r key characters. It specifies that new files are to be placed before posname in the archive file.

l
This option is obsolete. It is recognized, but ignored.

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

u
When used with the r key character, then only updated versions of files in the archive are used to overwrite the originals.

v
Give a verbose file-by-file description of the making of a new archive file from the old archive and the constituent files:

Exit values

ar returns 0 on success and non-zero on failure.

Warning

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

This utility determines object file format of input file and invokes the same binary, /usr/ccs/bin/elf/ar, on COFF, iBCS2, and ELF object files.

Files


$TMPDIR/*
temporary files

$TMPDIR is usually /usr/tmp but can be re-defined by setting the environment variable TMPDIR (see tempnam(S) in tmpnam(S)).


/usr/ccs/bin/elf/ar
invoked for COFF, iBCS2, and ELF object files

See also

a.out(FP), ar(FP), ld(CP), lorder(CP), strip(CP), tsort(CP), tmpnam(S)

Standards conformance

ar(CP) is conformant with:

X/Open Portability Guide, Issue 3, 1989 .


© 2003 Commands for Programming (CP)
SCO OpenServer Release 5.0.7 -- 11 February 2003