ar —
manage
archives
ar |
-d
[-f]
[-j]
[-T]
[-v]
[-z]
archive file
... |
ar |
-m
[-a
position-after]
[-b
position-before]
[-f]
[-i
position-before]
[-j]
[-s |
-S]
[-T]
[-z]
archive file
... |
ar |
-p
[-f]
[-s]
[-T]
[-v]
archive
[file ...] |
ar |
-q
[-c]
[-D]
[-f]
[-F
flavor |
--flavor
flavor]
[-s |
-S]
[-T]
[-U]
[-v]
[-z]
archive file
... |
ar |
-r
[-a
position-after]
[-b
position-before]
[-c]
[-D]
[-f]
[-F
flavor |
--flavor
flavor]
[-i
position-before]
[-j]
[-s |
-S]
[-T]
[-u]
[-U]
[-v]
[-z]
archive file
... |
ar |
-s
[-D]
[-j]
[-U]
[-z]
archive |
ar |
-t
[-f]
[-s]
[-T]
[-v]
archive
[file ...] |
ar |
-x
[-C]
[-f]
[-o]
[-s]
[-T]
[-u]
[-v]
archive
[file ...] |
The
ar utility creates and maintains groups of
files combined into an archive. 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 archive 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.
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
file ... 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 arguments
file ... are added after the archive
member named by argument
member-after.
-
-
- -b
member-before
- When used with option -m this
option specifies that the archive members specified by arguments
file ... 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 arguments
file ... 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
file ... from the archive specified by
argument archive. The archive's symbol
table, if present, is updated to reflect the new contents of the
archive.
-
-
- -D
- When used in combination with the
-r or -q option,
insert 0's instead of the real mtime, uid and gid values and 0644 instead
of file mode from the members named by arguments
file .... This ensures that checksums on
the resulting archives are reproducible when member contents are
identical. If multiple -D and
-U options are specified on the command line,
the final one takes precedence.
-
-
- -f
- Synonymous with option
-T.
-
-
- -F
flavor |
--flavor
flavor
- Create archives with the specified archive format. Legal
values for argument flavor are:
- bsd
- Create BSD format archives.
- gnu
- An alias for
svr4.
- svr4
- Create SVR4 format archives.
If this option is not specified, ar will create
archives using the SVR4 format.
-
-
- -i
member-before
- Synonymous with option
-b.
-
-
- -j
- This option is accepted for compatibility with the FreeBSD
version of the ar utility, but is
ignored.
-
-
- -l
- This option is accepted for compatibility with GNU
ar(1), but is ignored.
-
-
- -m
- Move archive members specified by arguments
file ... 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 specified 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.
-
-
- -M
- Read and execute MRI librarian commands from standard
input. The commands understood by the ar
utility are described in the section
MRI Librarian
Commands.
-
-
- -o
- Preserve the original modification times of members when
extracting them.
-
-
- -p
- Write the contents of the specified archive members named
by arguments file ... to standard output.
If no members were specified, 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
file ... to the archive specified by
argument archive without checking if the
files already exist in the archive. The archive symbol table will be
updated as needed. If the file specified by the argument
archive does not already exist, a new
archive will be created.
-
-
- -r
- Replace (add) the files specified by arguments
file ... in the archive specified by
argument archive, creating the archive if
necessary. Replacing existing members will not change the order of members
within the archive. If a file named in arguments
file ... 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(1).
-
-
- -S
- Do not generate an archive symbol table.
-
-
- -t
- For ar, list the files
specified by arguments file ... 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 file ... 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 file ... will be extracted only
if they are newer than the corresponding files in the file system.
-
-
- -U
- When used in combination with the
-r or -q option,
insert the real mtime, uid and gid, and file mode values from the members
named by arguments file .... If multiple
-D and -U
options are specified on the command line, the final one takes
precedence.
-
-
- -v
- Provide verbose output. When used with the
-d, -m,
-q or -x
options, ar gives a file-by-file description
of the archive modification 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 newline 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.
-
-
- -V
- Print a version identifier and exit.
-
-
- -x
- Extract archive members specified by arguments
file ... 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
- This option is accepted for compatibility with the FreeBSD
version of the ar utility, but is
ignored.
If the
-M option is specified, the
ar utility will read and execute commands from
its standard input. If standard input is a terminal, the
ar utility will display the prompt
“
AR >
” before reading a line, and
will continue operation even if errors are encountered. If standard input is
not a terminal, the
ar utility will not display a
prompt and will terminate execution on encountering an error.
Each input line contains a single command. Words in an input line are separated
by whitespace characters. The first word of the line is the command, the
remaining words are the arguments to the command. The command word may be
specified in either case. Arguments may be separated by commas or blanks.
Empty lines are allowed and are ignored. Long lines are continued by ending them
with the “
+
” character.
The “
*
” and
“
;
” characters start a comment. Comments
extend till the end of the line.
When executing an MRI librarian script the
ar
utility works on a temporary copy of an archive. Changes to the copy are made
permanent using the
save command.
Commands understood by the
ar utility are:
-
-
- addlib
archive |
addlib
archive
(member [,
member]...)
- Add the contents of the archive named by argument
archive to the current archive. If
specific members are named using the arguments
member, then those members are added to
the current archive. If no members are specified, the entire contents of
the archive are added to the current archive.
-
-
- addmod
member [,
member]...
- Add the files named by arguments
member to the current archive.
-
-
- clear
- Discard all the contents of the current archive.
-
-
- create
archive
- Create a new archive named by the argument
archive, and makes it the current
archive. If the named archive already exists, it will be overwritten when
the save command is issued.
-
-
- delete
module [,
member]...
- Delete the modules named by the arguments
member from the current archive.
-
-
- directory
archive
(member [,
member]...)
[outputfile]
- List each named module in the archive. The format of the
output depends on the verbosity setting set using the
verbose command. Output is sent to standard
output, or to the file specified by argument
outputfile.
-
-
- end
- Exit successfully from the ar
utility. Any unsaved changes to the current archive will be
discarded.
-
-
-
member [,
member]...
- Extract the members named by the arguments
member from the current archive.
-
-
- list
- Display the contents of the current archive in verbose
style.
-
-
- open
archive
- Open the archive named by argument
archive and make it the current
archive.
-
-
- replace
member [,
member]...
- Replace named members in the current archive with the files
specified by arguments member. The files
must be present in the current directory and the named modules must
already exist in the current archive.
-
-
- save
- Commit all changes to the current archive.
-
-
- verbose
- Toggle the verbosity of the
directory command.
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
To create a new archive
ex.a containing the files
ex1.o, and
ex2.o,
using MRI librarian commands, use the following script:
create ex.a * specify the output archive
addmod ex1.o ex2.o * add modules
save * save pending changes
end * exit the utility
The
ar utility exits 0 on success,
and >0 if an error occurs.
ld(1),
ranlib(1),
archive(3),
elf(3),
strftime(3),
strmode(3),
ar(5)
The
ar utility's support for the
-a,
-b,
-c,
-i,
-m,
-p,
-q,
-r,
-s,
-t,
-u,
-v,
-C and
-T options is
believed to be compliant with
IEEE Std 1003.2
(“POSIX.2”).
An
ar command first appeared in AT&T UNIX
Version 1. In
FreeBSD 8.0,
Kai Wang
<
kaiw@FreeBSD.org>
reimplemented
ar using the
Streaming Archive Library (libarchive,
-larchive) and the
ELF Access Library
(libelf, -lelf).