AR(1) AR(1)
NAME
ar - archive and library maintainer
SYNOPSIS
ar -d [-lv] archive file ...
ar -m [-lv] [-abi] [posname] archive file ...
ar -p [-ls] archive [file ...]
ar -q [-clzf] archive file ...
ar -r [-cuvsfl] [-abi] [posname] archive file ...
ar -t [-vs] archive [file ...]
ar -x [-vosCT] archive [file ...]
DESCRIPTION
The archiver (ar) maintains groups of files as a single archive file.
Generally, you use this utility to create and update library files that
the link editor uses; however, you can use the archiver for any similar
purpose.
This version of ar produces both 32-bit and 64-bit archives. The 32-bit
archive format is defined in the System V Release 4 ABI. The 64-bit
archive format is defined in the 64-bit ELF OBJECT File Specification.
32-bit objects and 64-bit objects cannot be mixed in an archive. The
first object determines whether the archive will be 32-bit or 64-bit, if
the archive does not exist to begin with. In compilers of version 7.x
and higher, the archiver also archives WHIRL objects. Mixing is allowed
between 32-bit relocatable ELF objects and 32-bit WHIRL objects, and
between 64-bit relocatable ELF objects and 64-bit WHIRL objects.
Different versions of WHIRL objects are NOT mixable.
If the environment variable _XPG is defined, ar operates in conformance
with the X/Open XPG4 specifications. The format of the output may differ
in accordance to the XPG4 standards. Changes are either in the exit
status or the format of the output.
Any option that changes an object library causes the archive-symbol-table
to be updated. This makes adding one file at a time to a library very
slow.
Useless options (such as using option -u with option -t) are not
diagnosed. NOTE: ar uses a portable ASCII-format archive that you can
use on various machines that run UNIX.
Options are documented here with a leading hyphen(-) form. An older form
with all option letters together and no leading hyphen is still
supported. The first example below shows the old form.
Examples:
ar cr lib.a a.o b.o
ar -c -r lib.a a.o b.o
ar -cr lib.a a.o b.o
Page 1
AR(1) AR(1)
Options are:
-a Position new files in the archive after the file named by the
posname operand. Use this suboption with the m or r options.
-b Position new files in the archive before the file named by the
posname operand. Use this suboption with the m or r options.
-c Suppress the normal message that the archiver prints when it creates
the archive file archive. Normally, the archiver creates the
specified archiver file when it needs to.
-C Prevent extracted files from replacing like-named files in the file
system. This option is useful when -T is also used, to prevent
truncated names from replacing files with the same prefix.
-d Delete the specified files from archive.
-i Position new files in the archive before the file named by the
posname operand (equivalent to -b). Use this suboption with the -m
or -r options.
-f Adds padding to the end of each object file archived, using the
character '\0'. This enables the loader (ld) to have faster access
to members in the archive while performing static linking. Warning:
this option results in the change in size of files permanently,
normally increased by 1 to 15 bytes. In compiler releases 7.1 and
higher, this option is the default.
-l Puts temporary files in the local directory. If option -l is not
supplied and the environment variable TMPDIR is defined then
TMPDIR's value is used as the name of the directory for temporary
files. If neither option -l nor TMPDIR is supplied, the archiver
puts its temporary files in the directory /tmp.
-m Moves the specified files to the end of the archive. If you specify
a positioning character, you must also specify the posname (as in
option -r) to tell the archiver where to move the files.
-o Force each newly created file to have the `last modified' date that
it had before it was extracted from the archive.
-p Prints the contents of the files from archive to the standard
output. If no files are specified, the contents of all files in the
archive will be written in the order of the archive.
-q Append the specified files to the end of the archive file. The
archiver does not accept suboption positioning characters with the
-q option. It also does not check whether the files you want to add
already exist in the archive. This is useful to bypass the
searching otherwise done when creating a large archive piece by
piece. Since the archive-symbol-table of an object library is
Page 2
AR(1) AR(1)
updated with -q it is advisable to add as many files as possible in
one execution of ar. Only -qz (see -z below) avoids quadratic
behavior when creating a large object archive piece by piece.
-r Replace or add files to archive. If the archive named by archive
does not exist, a new archive file will be created and a diagnostic
message will be written to standard error (unless the -c option is
specified). If no files are specified and the archive exists,
nothing is done. Files that replace existing files will not change
the order of the archive. If you use the suboption -u with -r, the
archiver only replaces those files that have `last-modified' dates
later than the archive files. If you use a positioning character
(from the set abi) you must specify the posname argument to tell the
archiver to put the new files after (a) or before (b or i).
Otherwise, the archiver puts new files at the end of the archive.
-s Makes an archive-symbol-table file in the archive. The -s option is
automatically added when any of the options -d, -m, or -r is
requested.
If you specify -s, the archiver creates the archive-symbol-table
file as its last action before finishing execution. You must
specify at least one other archive option (m, p, d, r, or t) when
you use the -s option.
-t Write a table of contents for the files in archive to the standard
output. If you don't specify any file names, write a table of
contents for all files in the order of the archave. If you specify
file names, the archiver writes a table of contents only for those
files.
-T Allow filename truncation of extracted files whose archive names are
longer than the file system can support. By default, extracting a
file with a name that is too long is an error; a diagnostic message
will be written and the file will not be extracted.
-u Update older files. When used with the -r option, files within the
archive will be replaced only if the corresponding file is newer
than the existing archive file. This option uses the UNIX system
`last-modified' date for this comparison. -u gives no warning when
replacement is refused.
-v Gives a verbose file-by-file description as the archiver makes a new
archive file from an old archive and its constituent files. When
you use this option with -t, the archiver lists, on standard output,
all information about the files in the archive. When you use this
option with -p, the archiver writes the name of the file to standard
output before writing the file itself to standard output. If you
add a second -v additional informational messages can appear.
Page 3
AR(1) AR(1)
-x Extract the files named by the file operands from the archive. The
contents of the archive file will not be changed. If you don't
specify any file names, the archiver extracts all files. Normally,
the `last-modified' date for each extracted file shows the date when
someone extracted it; however, when you use -o, the archiver resets
the `last-modified' date to the date recorded in the archive.
-z Only be useful with -q. -qz supresses updating of the archive-
symbol-table and updates the archive in-place. The resulting
archive cannot be used with ld (and is not a System V Release 4 ABI
compliant archive) until an archive-symbol-table update is done.
ld(1) will fail with a message suggesting use of ar -ts if the last
change to the archive uses -qz: Use of -qz is discouraged: the
updates are not checked for duplications and in case of a file or
other error the archive may be destroyed. If any file name added is
longer than 15 characters, line qz updates the archive-symbol-table
even with -qz. If all file names added with qz on a particular
execution are 15 characters or less the archive-symbol-table update
is suppressed (even if some file names already in the archive are
longer than 15 characters). x option.
FILES
/tmp/ar.tmp.v* or TMPDIR/ar.tmp.v* temporaries
SEE ALSO
lorder(1), ld(1), ar(4)
System V Application Binary Interface, ISBN 0-13-877598-2, Prentice Hall
NOTES
There is no ranlib program in IRIX. Option -s creates the archive-
symbol-table ld uses.
Options -r, -d, -m, and -q imply option -s. Since option -s creates an
archive-symbol-table, creating an object library by executing ar once per
object file will be very slow. Creating an object library with a single
execution of ar is much faster.
DIAGNOSTICS
xxxxx not found
The file xxxxx was not found in the archive. It could mean a simple
misspelling, but it could also mean that you supplied xxxxx more
than the number of times xxxxx appears in the archive! Files not
found change the exit code from ar but any attempted update of the
archive (by option r for example) is not suppressed.
not in archive format
You probably forgot to specify the archive name in the command.
The archive mentioned in the synopsis should be the archive name.
Page 4
AR(1) AR(1)
The diagnostics "s - creating Symbol hash table" and "s - done" are no
longer emitted when -v is used (to make the -v output standard-
conforming). If you really want to see those messages, add a second v,
as in -vv.
MORE NOTES
The behavior documented in this section is not guaranteed to remain the
same across releases. This section is provided as help in case ar does
something surprising.
If there is only one hard link (ie, at most one non-symbolic-link. see
ln(2)) to an archive which is being updated then an old archive contents
are replaced by the new contents by rename(2). Otherwise, when updating,
replacement is by copying the new data onto the old file. If the archive
is updated, the replacement archive is built in the same directory as the
named archive (after following symbolic links to the location of the
named archive).
In case the copy operation mentioned above is interrupted in mid-copy
(which is normally not possible) ar will attempt to set the archive
length to 0 and the modification-date to January 1, 1970 as a hint that
the archive is not usable.
If the ar command results in an unchanged archive, the old archive will
not be replaced. This is best achieved with, for example, ar ru lib.a
x.o; if the named object file is not put into the archive, the archive is
not modified. The definition of unchanged is very conservative: ar r
lib.a x.o, for example, always changes the archive since x.o is added or
replaced (even though x.o itself may be unchanged).
The following is a sampling of traditional ar behaviors that you may find
surprising.
If you specify the same file twice in an argument list, it can appear
twice in the archive file.
The o option does not change the `last-modified' date of a file unless
you own the extracted file or you are the super-user.
Trailing slashes are removed from file-path-names. Only the final
component of a file-path-name is recorded in an archive. For example, in
/a/b/c/dfile//// the file searched for is /a/b/c/dfile and the name
recorded in the archive is dfile.
If you give ar the same name twice in an ar x command the second instance
of the name will provoke a ``not found'' message.
Page 5