ar(1) ar(1)
NAME
ar - archive and library maintainer
SYNOPSIS
ar [-V] mainkey [modifier]... [posname] [--] afile [filename]...
DESCRIPTION
ar is used to maintain archives (libraries).
-V ar prints its version number on standard error.
In specific terms, you can use ar to perform the following file
management functions:
_____________________________________________________________
| Function | Main keys|
|________________________________________________|___________|
| create an archive file | -q or -r |
|________________________________________________|___________|
| quickly append a file to the end of the archive| -q |
|________________________________________________|___________|
| place/replace a file in the archive | -r |
|________________________________________________|___________|
| delete a file from the archive | -d |
|________________________________________________|___________|
| move a file within the archive | -m |
|________________________________________________|___________|
| print the contents of a file | -p |
|________________________________________________|___________|
| list the files in the archive | -t |
|________________________________________________|___________|
| copy (extract) a file from the archive | -x |
|________________________________________________|___________|
Structure of an archive
An archive is a single file that combines several files into one. By
convention, the name of an archive file ends with the suffix .a. The
purpose of an archive file is to enable the collective maintenance of
a group of related files. Archives make it easier to maintain files,
since you will often only need to specify the archive file instead of
individually listing all its elements.
The constituents of an archive are typically object modules that usu-
ally form part of the same program or suite of programs.
The magic string and the file headers used by ar consist of printable
ASCII characters. If an archive is entirely 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 (for the portable archive format and
structure [see ar(4)].
Page 1 Reliant UNIX 5.44 Printed 11/98
ar(1) ar(1)
If the archive contains at least one object file, ar creates and main-
tains an archive symbol table. This symbol table is used by the link
editor ld to effect multiple passes over the archive in an efficient
manner. The archive symbol table is stored in a specially named file
that is always the first file in the archive. This file is never
listed or printed out like other archive files and is not accessible
to the user. Whenever the ar command is used to create or update the
contents of an archive, the symbol table is rebuilt. The symbol table
can also be rebuilt by calling ar with the -s option.
OPTIONS
Main keys
When you call ar, you must specify precisely one main key (-d, -m, -p,
-q, -r, -t or -x), optionally followed by one or more arguments.
-d ar deletes the specified files from the archive. If no files are
specified, no action is taken.
-m ar moves the specified files within the archive.
With posname:
The files are placed after (-a) or before (-b or -i) the file
named posname (see posname).
Without posname:
The files are appended to the end of the archive.
-p ar prints the contents of the specified files. If no files are
given, the contents of all files are printed.
-q The specified files are added to the archive "quickly", i.e.:
- if the archive already exists, ar appends the named files to
it without checking whether they are already present in the
archive;
- if the archive does not yet exist, it is created.
No posname arguments are permitted.
The -q option is useful when creating a large archive piece-by-
piece.
-r (replace) This option has three different effects, depending on
whether the specified archive exists and whether it contains the
named files:
- If the archive exists and contains the files, ar replaces the
named files.
Page 2 Reliant UNIX 5.44 Printed 11/98
ar(1) ar(1)
- If the archive exists but is missing one or more of the named
files, ar adds the missing files to the archive.
- If the archive does not exist, ar creates the archive from the
named files.
With modifier -u:
ar replaces a file in the archive only if the named file has a
later date of last modification than the version already in the
archive.
With posname:
Files not yet in the archive are placed after (-a) or before (-b
or -i) the file posname (see posname).
Without posname:
Files not yet in the archive are appended to the end of the
archive.
-t ar prints a table of contents of the archive file. If no files
are specified, all files in the archive are listed; otherwise,
only the named files.
-x ar copies (extracts) files from the archive.
If no files are specified, all files in the archive are
extracted. The archive itself remains unaltered.
Key modifiers
-c (create) The message that ar usually issues when creating an
archive is suppressed.
-C (C - create) Protection against overwriting. -C prevents files
extracted using -x from replacing like-named files.
-l (l - local) Temporary files are placed in the current directory.
-s (symbol table) ar regenerates the archive symbol table (even if
the archive contents have not been modified). This modifier is
useful to restore the archive symbol table after the strip com-
mand has been used on the archive [see strip(1)].
Page 3 Reliant UNIX 5.44 Printed 11/98
ar(1) ar(1)
-T (T - truncate) ar truncates filenames if they are too long for
the current file system. For security reasons, this option should
only be used together with -C.
-T not specified:
Files whose names are too long are not extracted by ar.
-u (update) See main key -r.
-v (verbose) ar reports each action it takes (adding files to the
archive, moving them within the archive, extracting them from the
archive, etc.). If -v is used with the -t key, ar displays a long
listing similar to that produced by the ls -l command [see
ls(1)].
posname
The posname argument specifies the position at which a file is
inserted into the archive. posname may be:
-a posfile
ar places the file after the named posfile.
-b posfile
-i posfile
ar inserts the file before the named posfile.
posfile is the name of a file already in the archive.
-- If afile begins with a dash (-), the end of the command-line
options must be marked with --.
afile
Name of the archive to be created or processed.
filename
Name of the file to be listed, printed out, added to, extracted
from, or moved within the archive.
More than one file may be named on the command line. If you
specify the same file more than once when calling ar with the -q
or -r key, ar will enter the named file into the archive as often
as specified. If a number of identically named files are con-
tained in the archive, and you use ar without specifying a posi-
tion, the first file with the given name will be accessed (rather
than the most recent or oldest file, for example).
Page 4 Reliant UNIX 5.44 Printed 11/98
ar(1) ar(1)
LOCALE
The LCMESSAGES environment variable governs the language in which
message texts are displayed.
The LCTIME environment variable governs the format of date and time
strings in archive content listings produced in conjunction with the v
modifier.
If LCMESSAGES or LCTIME is undefined or is defined as the null
string, it defaults to the value of LANG. If LANG is likewise unde-
fined or null, the system acts as if it were not internationalized.
If any of the locale variables has an invalid value, the system acts
as if none of the variables were set.
The LCALL environment variable governs the entire locale. LCALL
takes precedence over all the other environment variables which affect
internationalization.
EXAMPLES
Example 1
Quickly creating an archive file:
$ ar -q -v afile.a atoi.o itoa.o
ar: creating afile.a
a - atoi.o
a - itoa.o
ar creates the archive afile.a from the files atoi.o and itoa.o. The v
modifier tells ar to display the names of the files as they are added.
Example 2
Placing a new file at a specified position in an archive:
$ ar -r -v -b atoi.o afile.a atof.o
a - atof.o
ar copies atof.o into the archive file afile.a, placing it before
atoi.o.
Example 3
Printing the table of contents of an archive:
$ ar -t -v afile.a
rw-r--r-- 104/ 1 2276 Jul 13 12:17 1990 atof.o
rw-r--r-- 104/ 1 759 Jul 13 12:17 1990 atoi.o
rw-r--r-- 104/ 1 1280 Jul 13 12:17 1990 itoa.o
Page 5 Reliant UNIX 5.44 Printed 11/98
ar(1) ar(1)
Example 4
Extracting (copying) a file from an archive:
$ ar -x -v afile.a atoi.o
x - atoi.o
The file atoi.o is copied from the archive afile.a into the working
directory. The copy is also called atoi.o.
SEE ALSO
cpio(1), ld(1), lorder(1), pax(1), strip(1), tar(1), a.out(4), ar(4).
Page 6 Reliant UNIX 5.44 Printed 11/98