AR(1) BSD General Commands Manual AR(1)NAME
ar, ranlib — manage archives
SYNOPSIS
ar -d [-T] [-j] [-v] [-z] archive files ...
ar -m [-T] [-a position-after] [-b position-before] [-i position-before]
[-j] [-s] [-z] archive files ...
ar -p [-T] [-v] archive [files ...]
ar -r [-T] [-a position-after] [-b position-before] [-c]
[-i position-before] [-j] [-s] [-u] [-v] [-z] archive files ...
ar -s [-j] [-z] archive
ar -t [-T] [-v] archive [files ...]
ar -x [-C] [-T] [-o] [-u] [-v] archive [files ...]
ranlib archive ...
DESCRIPTION
The ar utility creates and maintains groups of files combined into an ar‐
chive. Once an archive has been created, new files can be added to it,
and existing files can be extracted, deleted or replaced.
Files are named in the archive by their last file name component, so if a
file referenced by a path containing a “/” is archived, it will be named
by the last component of the path. Similarly when matching paths listed
on the command line against file names stored in the archive, only the
last component of the path will be compared.
The normal use of ar is for the creation and maintenance of libraries
suitable for use with the link editor ld(1), although it is not
restricted to this purpose. The ar utility can create and manage an ar‐
chive symbol table (see ar(5)) used to speed up link editing operations.
If a symbol table is present in an archive, it will be kept up-to-date by
subsequent operations on the archive (excepting the quick update speci‐
fied by the -q option).
The ranlib utility is used to add an archive symbol table to an existing
archive.
OPTIONS
The ar utility supports the following options:
-a member-after
When used with option -m this option specifies that the archive
members specified by arguments files ... are moved to after the
archive member named by argument member-after. When used with
option -r this option specifies that the files specified by argu‐
ments files ... are added after the archive member named by argu‐
ment member-after.
-b member-before
When used with option -m this option specifies that the archive
members specified by arguments files ... are moved to before the
archive member named by argument member-before. When used with
option -r this option specifies that the files specified by argu‐
ments files ... are added before the archive member named by
argument member-before.
-c Suppress the informational message printed when a new archive is
created using the -r and -q options.
-C Prevent extracted files from replacing like-named files in the
file system.
-d Delete the members named by arguments files ... from the archive
specified by argument archive. The archive's symbol table, if
present, is updated to reflect the new contents of the archive.
-f Synonymous with option -T.
-i member-before
Synonymous with option -b.
-j Compress the resulting archive with bzip2(1).
-m Move archive members specified by arguments files ... within the
archive. If a position has been specified by one of the -a, -b
or -i options, the members are moved to before or after the spec‐
ified position. If no position has been specified, the specified
members are moved to the end of the archive. If the archive has
a symbol table, it is updated to reflect the new contents of the
archive.
-o Preserve the original modification times of members when extract‐
ing them.
-p Write the contents of the specified archive members named by
arguments files ... to standard output. If no members were spec‐
ified, the contents of all the files in the archive are written
in the order they appear in the archive.
-q Append the files specified by arguments files ... to the archive
specified by argument archive without checking if the files
already exist in the archive and without updating the archive's
symbol table. If the archive file archive does not already
exist, a new archive is created. However, to be compatible with
GNU ar, option -q will update the archive's symbol table.
-r Replace (add) the files specified by arguments files ... in the
archive specified by argument archive, creating the archive if
necessary. Files that replace existing files do not change the
order of files within the archive. If a file named in arguments
files ... does not exist, existing members in the archive that
match that name are not changed. New files are added to the end
of the archive unless one of the positioning options -a, -b or -i
is specified. The archive symbol table, if it exists, is updated
to reflect the new state of the archive.
-s Add an archive symbol table (see ar(5)) to the archive specified
by argument archive. Invoking ar with the -s option alone is
equivalent to invoking ranlib.
-t List the files specified by arguments files ... in the order in
which they appear in the archive, one per line. If no files are
specified, all files in the archive are listed.
-T Use only the first fifteen characters of the archive member name
or command line file name argument when naming archive members.
-u Conditionally update the archive or extract members. When used
with the -r option, files named by arguments files ... will be
replaced in the archive if they are newer than their archived
versions. When used with the -x option, the members specified by
arguments files ... will be extracted only if they are newer than
the corresponding files in the file system.
-v Provide verbose output. When used with the -d, -m, -q or -x
options, ar gives a file-by-file description of the archive modi‐
fication being performed, which consists of three white-space
separated fields: the option letter, a dash “-”, and the file
name. When used with the -r option, ar displays the description
as above, but the initial letter is an “a” if the file is added
to the archive, or an “r” if the file replaces a file already in
the archive. When used with the -p option, the name of the file
enclosed in “<” and “>” characters is written to standard output
preceded by a single newline character and followed by two new‐
line characters. The contents of the named file follow the file
name. When used with the -t option, ar displays eight whitespace
separated fields: the file permissions as displayed by
strmode(3), decimal user and group IDs separated by a slash (
“/”), the file size in bytes, the file modification time in
strftime(3) format “%b %e %H:%M %Y”, and the name of the file.
-x Extract archive members specified by arguments files ... into the
current directory. If no members have been specified, extract
all members of the archive. If the file corresponding to an
extracted member does not exist it will be created. If the file
corresponding to an extracted member does exist, its owner and
group will not be changed while its contents will be overwritten
and its permissions will set to that entered in the archive. The
file's access and modification time would be that of the time of
extraction unless the -o option was specified.
-z Compress the resulting archive with gzip(1).
EXAMPLES
To create a new archive ex.a containing three files ex1.o, ex2.o and
ex3.o, use:
ar -rc ex.a ex1.o ex2.o ex3.o
To add an archive symbol table to an existing archive ex.a, use:
ar -s ex.a
To delete file ex1.o from archive ex.a, use:
ar -d ex.a ex1.o
To verbosely list the contents of archive ex.a, use:
ar -tv ex.a
DIAGNOSTICS
The ar utility exits 0 on success, and >0 if an error occurs.
SEE ALSOld(1), archive(3), elf(3), strftime(3), strmode(3), ar(5)HISTORY
An ar command first appeared in AT&T UNIX Version 1. In FreeBSD 8.0, Kai
Wang ⟨kaiw@FreeBSD.org⟩ reimplemented ar and ranlib using the library
“libarchive” and the library “libelf”.
BSD August 31, 2007 BSD