ar
PURPOSE
Maintains portable libraries used by the linkage editor.
SYNOPSIS
ar key [ posname ] afile name ...
DESCRIPTION
The ar command combines one or more named files into a
single library file written in ar archive format. When
ar creates a library, it creates headers in a transport-
able format; when it creates or updates a library, it
rebuilds the symbol table that the linkage editor (the ld
command) uses to make efficient multiple passes over
object file libraries. See the ar file entry in AIX
Operating System Technical Reference for information on
the format and structure of portable archives and symbol
tables.
FLAGS
In an ar command, you must list all selected flags
together on the command line without blanks between them.
You must specify one from the set dhmpqrtxw. You can
also specify any number of optional flags from the set
abcilsuv. If you select a positioning flag (a, b, or i),
you must also specify the name of a file within library
(posname), immediately following the flag list and sepa-
rated from it by a blank.
a posname
Positions the named files after the existing file
identified by posname.
b posname
Positions the named files before the existing
file identified by posname.
c Suppresses the normal message that is produced
when library is created.
d Deletes the named files from the library.
h Sets the modification times in the member headers
of the named files to the current date and time.
If you do not specify any file names, ar sets the
time stamps of all member headers.
i posname
Positions the named files before the existing
file identified by posname (same as b).
l Places temporary files in the current (local)
directory instead of directory /tmp.
m Moves the named files to some other position in
the library. By default, it moves the named
files to the end of the library. Use a posi-
tioning flag (abi) to specify some other posi-
tion.
p Writes to the standard output the contents of the
named files or all files in a library if you do
not specify any files.
q Adds the named files to the end of the library.
Positioning flags, if present, do not have any
effect. Note that this process does not check to
see if the named files are already in the
library. In addition, if you name the same file
twice, it may be put in the library twice.
r Replaces a named file if it already appears in
the library. Since the named files occupy the
same position in the library as the files they
replace, a positioning flag does not have any
additional effect. When used with the u flag
(update), r replaces only files modified since
they were last added to the library file.
If a named file does not already appear in the
library, ar adds it. In this case, positioning
flags do affect placement. If you do not specify
a position, new files are placed at the end of
the library. If you name the same file twice, it
may be put in the library twice.
s Forces the regeneration of the library symbol
table whether or not ar modifies the library con-
tents. Use this flag to restore the library
symbol table after using the strip command on the
library.
t Writes to the standard output a table of contents
for the library. If you specify file names, only
those files appear. If you do not specify any
files, t lists all files in the library.
u Copies only files which have been changed since
they were last copied (see the r flag discussed
previously).
v Writes to standard output a verbose file-by-file
description of the making of the new library.
When used with the t flag, it gives a long
listing similar to that of the ls -l command,
described under "ls." When used with the x
flag, it precedes each file with a name. When
used with the h flag, it lists the member name
and the updated modification times.
The environment variables NLLDATE and NLTIME
control the format of the archive date and time.
w Displays the archive symbol table. Each symbol
is listed with the name of the file in which the
symbol is defined.
x Extracts the named files by copying them into the
current directory. These copies have the same
name as the original files, which remain in the
library. If you do not specify any files, x
copies all files out of the library. This
process does not alter the library.
EXAMPLES
1. To create a library:
ar vq lib.a strlen.o strcpy.o
If "lib.a" does not exist, then this creates it and
enters into it copies of the files "strlen.o" and
"strcpy.o". If "lib.a" does exist, then this adds
the new members to the end without checking for
duplicate members. The v flag sets verbose mode, in
which ar displays progress reports as it proceeds.
2. To list the table of contents of a library:
ar vt lib.a
This lists the table of contents of "lib.a", dis-
playing a long listing similar to ls -l. To list
only the member file names, omit the v flag.
3. To replace or add new members to a library:
ar vr lib.a strlen.o strcat.o
This replaces the members "strlen.o" and "strcat.o".
If "lib.a" was created as shown in Example 1, then
the "strlen.o" member is replaced. A member named
"strcat.o" does not already exist, so it is added to
the end of the library.
4. To specify where to insert a new member:
ar vrb strlen.o lib.a strcmp.o
This adds "strcmp.o", placing the new member before
"strlen.o".
5. To update a member if it has been changed:
ar vru lib.a strcpy.o
This replaces the existing "strcpy.o" member, but
only if the file "strcpy.o" has been modified since
it was last added to the library.
6. To change the order of the library members:
ar vma strcmp.o lib.a strcat.o strcpy.o
This moves the members "strcat.o" and "strcpy.o" to
positions immediately after "strcmp.o". The relative
order of "strcat.o" and "strcpy.o" is preserved. In
other words, if "strcpy.o" preceded "strcat.o" before
the move, then it still does.
7. To extract library members:
ar vx lib.a strcat.o strcpy.o
This copies the members "strcat.o" and "strcpy.o"
into individual files named "strcat.o" and
"strcpy.o", respectively.
8. To extract and rename a member:
ar p lib.a strcpy.o >stringcopy.o
This copies the member "strcpy.o" to a file named
"stringcopy.o".
9. To delete a member:
ar vd lib.a strlen.o
This deletes the member "strlen.o" from the library
"lib.a".
FILES
/tmp/ar* Temporary files.
RELATED INFORMATION
The following commands: "backup," "ld," "lorder,"
"make," "nm," "size," and "strip."
The a.out and ar files and environment miscellaneous
facility in AIX Operating System Technical Reference.
The "Overview of International Character Support" in Man-
aging the AIX Operating System.