461 lines
19 KiB
Groff
461 lines
19 KiB
Groff
.\" -*- mode: troff; coding: utf-8 -*-
|
|
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
|
|
.\"
|
|
.\" Standard preamble:
|
|
.\" ========================================================================
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Vb \" Begin verbatim text
|
|
.ft CW
|
|
.nf
|
|
.ne \\$1
|
|
..
|
|
.de Ve \" End verbatim text
|
|
.ft R
|
|
.fi
|
|
..
|
|
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
|
|
.ie n \{\
|
|
. ds C` ""
|
|
. ds C' ""
|
|
'br\}
|
|
.el\{\
|
|
. ds C`
|
|
. ds C'
|
|
'br\}
|
|
.\"
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\"
|
|
.\" If the F register is >0, we'll generate index entries on stderr for
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
|
.\" output yourself in some meaningful fashion.
|
|
.\"
|
|
.\" Avoid warning from groff about undefined register 'F'.
|
|
.de IX
|
|
..
|
|
.nr rF 0
|
|
.if \n(.g .if rF .nr rF 1
|
|
.if (\n(rF:(\n(.g==0)) \{\
|
|
. if \nF \{\
|
|
. de IX
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
|
..
|
|
. if !\nF==2 \{\
|
|
. nr % 0
|
|
. nr F 2
|
|
. \}
|
|
. \}
|
|
.\}
|
|
.rr rF
|
|
.\" ========================================================================
|
|
.\"
|
|
.IX Title "AR 1"
|
|
.TH AR 1 1980-01-01 binutils-2.40.90 "GNU Development Tools"
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
|
.\" way too many mistakes in technical documents.
|
|
.if n .ad l
|
|
.nh
|
|
.SH NAME
|
|
ar \- create, modify, and extract from archives
|
|
.SH SYNOPSIS
|
|
.IX Header "SYNOPSIS"
|
|
ar [\fB\-X32_64\fR] [\fB\-\fR]\fIp\fR[\fImod\fR] [\fB\-\-plugin\fR \fIname\fR] [\fB\-\-target\fR \fIbfdname\fR] [\fB\-\-output\fR \fIdirname\fR] [\fB\-\-record\-libdeps\fR \fIlibdeps\fR] [\fB\-\-thin\fR] [\fIrelpos\fR] [\fIcount\fR] \fIarchive\fR [\fImember\fR...]
|
|
.SH DESCRIPTION
|
|
.IX Header "DESCRIPTION"
|
|
The GNU \fBar\fR program creates, modifies, and extracts from
|
|
archives. An \fIarchive\fR is a single file holding a collection of
|
|
other files in a structure that makes it possible to retrieve
|
|
the original individual files (called \fImembers\fR of the archive).
|
|
.PP
|
|
The original files' contents, mode (permissions), timestamp, owner, and
|
|
group are preserved in the archive, and can be restored on
|
|
extraction.
|
|
.PP
|
|
GNU \fBar\fR can maintain archives whose members have names of any
|
|
length; however, depending on how \fBar\fR is configured on your
|
|
system, a limit on member-name length may be imposed for compatibility
|
|
with archive formats maintained with other tools. If it exists, the
|
|
limit is often 15 characters (typical of formats related to a.out) or 16
|
|
characters (typical of formats related to coff).
|
|
.PP
|
|
\&\fBar\fR is considered a binary utility because archives of this sort
|
|
are most often used as \fIlibraries\fR holding commonly needed
|
|
subroutines. Since libraries often will depend on other libraries,
|
|
\&\fBar\fR can also record the dependencies of a library when the
|
|
\&\fB\-\-record\-libdeps\fR option is specified.
|
|
.PP
|
|
\&\fBar\fR creates an index to the symbols defined in relocatable
|
|
object modules in the archive when you specify the modifier \fBs\fR.
|
|
Once created, this index is updated in the archive whenever \fBar\fR
|
|
makes a change to its contents (save for the \fBq\fR update operation).
|
|
An archive with such an index speeds up linking to the library, and
|
|
allows routines in the library to call each other without regard to
|
|
their placement in the archive.
|
|
.PP
|
|
You may use \fBnm \-s\fR or \fBnm \-\-print\-armap\fR to list this index
|
|
table. If an archive lacks the table, another form of \fBar\fR called
|
|
\&\fBranlib\fR can be used to add just the table.
|
|
.PP
|
|
GNU \fBar\fR can optionally create a \fIthin\fR archive,
|
|
which contains a symbol index and references to the original copies
|
|
of the member files of the archive. This is useful for building
|
|
libraries for use within a local build tree, where the relocatable
|
|
objects are expected to remain available, and copying the contents of
|
|
each object would only waste time and space.
|
|
.PP
|
|
An archive can either be \fIthin\fR or it can be normal. It cannot
|
|
be both at the same time. Once an archive is created its format
|
|
cannot be changed without first deleting it and then creating a new
|
|
archive in its place.
|
|
.PP
|
|
Thin archives are also \fIflattened\fR, so that adding one thin
|
|
archive to another thin archive does not nest it, as would happen with
|
|
a normal archive. Instead the elements of the first archive are added
|
|
individually to the second archive.
|
|
.PP
|
|
The paths to the elements of the archive are stored relative to the
|
|
archive itself.
|
|
.PP
|
|
GNU \fBar\fR is designed to be compatible with two different
|
|
facilities. You can control its activity using command-line options,
|
|
like the different varieties of \fBar\fR on Unix systems; or, if you
|
|
specify the single command-line option \fB\-M\fR, you can control it
|
|
with a script supplied via standard input, like the MRI "librarian"
|
|
program.
|
|
.SH OPTIONS
|
|
.IX Header "OPTIONS"
|
|
GNU \fBar\fR allows you to mix the operation code \fIp\fR and modifier
|
|
flags \fImod\fR in any order, within the first command-line argument.
|
|
.PP
|
|
If you wish, you may begin the first command-line argument with a
|
|
dash.
|
|
.PP
|
|
The \fIp\fR keyletter specifies what operation to execute; it may be
|
|
any of the following, but you must specify only one of them:
|
|
.IP \fBd\fR 4
|
|
.IX Item "d"
|
|
\&\fIDelete\fR modules from the archive. Specify the names of modules to
|
|
be deleted as \fImember\fR...; the archive is untouched if you
|
|
specify no files to delete.
|
|
.Sp
|
|
If you specify the \fBv\fR modifier, \fBar\fR lists each module
|
|
as it is deleted.
|
|
.IP \fBm\fR 4
|
|
.IX Item "m"
|
|
Use this operation to \fImove\fR members in an archive.
|
|
.Sp
|
|
The ordering of members in an archive can make a difference in how
|
|
programs are linked using the library, if a symbol is defined in more
|
|
than one member.
|
|
.Sp
|
|
If no modifiers are used with \f(CW\*(C`m\*(C'\fR, any members you name in the
|
|
\&\fImember\fR arguments are moved to the \fIend\fR of the archive;
|
|
you can use the \fBa\fR, \fBb\fR, or \fBi\fR modifiers to move them to a
|
|
specified place instead.
|
|
.IP \fBp\fR 4
|
|
.IX Item "p"
|
|
\&\fIPrint\fR the specified members of the archive, to the standard
|
|
output file. If the \fBv\fR modifier is specified, show the member
|
|
name before copying its contents to standard output.
|
|
.Sp
|
|
If you specify no \fImember\fR arguments, all the files in the archive are
|
|
printed.
|
|
.IP \fBq\fR 4
|
|
.IX Item "q"
|
|
\&\fIQuick append\fR; Historically, add the files \fImember\fR... to the end of
|
|
\&\fIarchive\fR, without checking for replacement.
|
|
.Sp
|
|
The modifiers \fBa\fR, \fBb\fR, and \fBi\fR do \fInot\fR affect this
|
|
operation; new members are always placed at the end of the archive.
|
|
.Sp
|
|
The modifier \fBv\fR makes \fBar\fR list each file as it is appended.
|
|
.Sp
|
|
Since the point of this operation is speed, implementations of
|
|
\&\fBar\fR have the option of not updating the archive's symbol
|
|
table if one exists. Too many different systems however assume that
|
|
symbol tables are always up-to-date, so GNU \fBar\fR will
|
|
rebuild the table even with a quick append.
|
|
.Sp
|
|
Note \- GNU \fBar\fR treats the command \fBqs\fR as a
|
|
synonym for \fBr\fR \- replacing already existing files in the
|
|
archive and appending new ones at the end.
|
|
.IP \fBr\fR 4
|
|
.IX Item "r"
|
|
Insert the files \fImember\fR... into \fIarchive\fR (with
|
|
\&\fIreplacement\fR). This operation differs from \fBq\fR in that any
|
|
previously existing members are deleted if their names match those being
|
|
added.
|
|
.Sp
|
|
If one of the files named in \fImember\fR... does not exist, \fBar\fR
|
|
displays an error message, and leaves undisturbed any existing members
|
|
of the archive matching that name.
|
|
.Sp
|
|
By default, new members are added at the end of the file; but you may
|
|
use one of the modifiers \fBa\fR, \fBb\fR, or \fBi\fR to request
|
|
placement relative to some existing member.
|
|
.Sp
|
|
The modifier \fBv\fR used with this operation elicits a line of
|
|
output for each file inserted, along with one of the letters \fBa\fR or
|
|
\&\fBr\fR to indicate whether the file was appended (no old member
|
|
deleted) or replaced.
|
|
.IP \fBs\fR 4
|
|
.IX Item "s"
|
|
Add an index to the archive, or update it if it already exists. Note
|
|
this command is an exception to the rule that there can only be one
|
|
command letter, as it is possible to use it as either a command or a
|
|
modifier. In either case it does the same thing.
|
|
.IP \fBt\fR 4
|
|
.IX Item "t"
|
|
Display a \fItable\fR listing the contents of \fIarchive\fR, or those
|
|
of the files listed in \fImember\fR... that are present in the
|
|
archive. Normally only the member name is shown, but if the modifier
|
|
\&\fBO\fR is specified, then the corresponding offset of the member is also
|
|
displayed. Finally, in order to see the modes (permissions), timestamp,
|
|
owner, group, and size the \fBv\fR modifier should be included.
|
|
.Sp
|
|
If you do not specify a \fImember\fR, all files in the archive
|
|
are listed.
|
|
.Sp
|
|
If there is more than one file with the same name (say, \fBfie\fR) in
|
|
an archive (say \fBb.a\fR), \fBar t b.a fie\fR lists only the
|
|
first instance; to see them all, you must ask for a complete
|
|
listing\-\-\-in our example, \fBar t b.a\fR.
|
|
.IP \fBx\fR 4
|
|
.IX Item "x"
|
|
\&\fIExtract\fR members (named \fImember\fR) from the archive. You can
|
|
use the \fBv\fR modifier with this operation, to request that
|
|
\&\fBar\fR list each name as it extracts it.
|
|
.Sp
|
|
If you do not specify a \fImember\fR, all files in the archive
|
|
are extracted.
|
|
.Sp
|
|
Files cannot be extracted from a thin archive, and there are
|
|
restrictions on extracting from archives created with \fBP\fR: The
|
|
paths must not be absolute, may not contain \f(CW\*(C`..\*(C'\fR, and any
|
|
subdirectories in the paths must exist. If it is desired to avoid
|
|
these restrictions then used the \fB\-\-output\fR option to specify
|
|
an output directory.
|
|
.PP
|
|
A number of modifiers (\fImod\fR) may immediately follow the \fIp\fR
|
|
keyletter, to specify variations on an operation's behavior:
|
|
.IP \fBa\fR 4
|
|
.IX Item "a"
|
|
Add new files \fIafter\fR an existing member of the
|
|
archive. If you use the modifier \fBa\fR, the name of an existing archive
|
|
member must be present as the \fIrelpos\fR argument, before the
|
|
\&\fIarchive\fR specification.
|
|
.IP \fBb\fR 4
|
|
.IX Item "b"
|
|
Add new files \fIbefore\fR an existing member of the
|
|
archive. If you use the modifier \fBb\fR, the name of an existing archive
|
|
member must be present as the \fIrelpos\fR argument, before the
|
|
\&\fIarchive\fR specification. (same as \fBi\fR).
|
|
.IP \fBc\fR 4
|
|
.IX Item "c"
|
|
\&\fICreate\fR the archive. The specified \fIarchive\fR is always
|
|
created if it did not exist, when you request an update. But a warning is
|
|
issued unless you specify in advance that you expect to create it, by
|
|
using this modifier.
|
|
.IP \fBD\fR 4
|
|
.IX Item "D"
|
|
Operate in \fIdeterministic\fR mode. When adding files and the archive
|
|
index use zero for UIDs, GIDs, timestamps, and use consistent file modes
|
|
for all files. When this option is used, if \fBar\fR is used with
|
|
identical options and identical input files, multiple runs will create
|
|
identical output files regardless of the input files' owners, groups,
|
|
file modes, or modification times.
|
|
.Sp
|
|
If \fIbinutils\fR was configured with
|
|
\&\fB\-\-enable\-deterministic\-archives\fR, then this mode is on by default.
|
|
It can be disabled with the \fBU\fR modifier, below.
|
|
.IP \fBf\fR 4
|
|
.IX Item "f"
|
|
Truncate names in the archive. GNU \fBar\fR will normally permit file
|
|
names of any length. This will cause it to create archives which are
|
|
not compatible with the native \fBar\fR program on some systems. If
|
|
this is a concern, the \fBf\fR modifier may be used to truncate file
|
|
names when putting them in the archive.
|
|
.IP \fBi\fR 4
|
|
.IX Item "i"
|
|
Insert new files \fIbefore\fR an existing member of the
|
|
archive. If you use the modifier \fBi\fR, the name of an existing archive
|
|
member must be present as the \fIrelpos\fR argument, before the
|
|
\&\fIarchive\fR specification. (same as \fBb\fR).
|
|
.IP \fBl\fR 4
|
|
.IX Item "l"
|
|
Specify dependencies of this library. The dependencies must immediately
|
|
follow this option character, must use the same syntax as the linker
|
|
command line, and must be specified within a single argument. I.e., if
|
|
multiple items are needed, they must be quoted to form a single command
|
|
line argument. For example \fBL "\-L/usr/local/lib \-lmydep1 \-lmydep2"\fR
|
|
.IP \fBN\fR 4
|
|
.IX Item "N"
|
|
Uses the \fIcount\fR parameter. This is used if there are multiple
|
|
entries in the archive with the same name. Extract or delete instance
|
|
\&\fIcount\fR of the given name from the archive.
|
|
.IP \fBo\fR 4
|
|
.IX Item "o"
|
|
Preserve the \fIoriginal\fR dates of members when extracting them. If
|
|
you do not specify this modifier, files extracted from the archive
|
|
are stamped with the time of extraction.
|
|
.IP \fBO\fR 4
|
|
.IX Item "O"
|
|
Display member offsets inside the archive. Use together with the \fBt\fR
|
|
option.
|
|
.IP \fBP\fR 4
|
|
.IX Item "P"
|
|
Use the full path name when matching or storing names in the archive.
|
|
Archives created with full path names are not POSIX compliant, and
|
|
thus may not work with tools other than up to date GNU tools.
|
|
Modifying such archives with GNU \fBar\fR without using
|
|
\&\fBP\fR will remove the full path names unless the archive is a
|
|
thin archive. Note that \fBP\fR may be useful when adding files to
|
|
a thin archive since \fBr\fR without \fBP\fR ignores the path
|
|
when choosing which element to replace. Thus
|
|
.Sp
|
|
.Vb 1
|
|
\& ar rcST archive.a subdir/file1 subdir/file2 file1
|
|
.Ve
|
|
.Sp
|
|
will result in the first \f(CW\*(C`subdir/file1\*(C'\fR being replaced with
|
|
\&\f(CW\*(C`file1\*(C'\fR from the current directory. Adding \fBP\fR will
|
|
prevent this replacement.
|
|
.IP \fBs\fR 4
|
|
.IX Item "s"
|
|
Write an object-file index into the archive, or update an existing one,
|
|
even if no other change is made to the archive. You may use this modifier
|
|
flag either with any operation, or alone. Running \fBar s\fR on an
|
|
archive is equivalent to running \fBranlib\fR on it.
|
|
.IP \fBS\fR 4
|
|
.IX Item "S"
|
|
Do not generate an archive symbol table. This can speed up building a
|
|
large library in several steps. The resulting archive can not be used
|
|
with the linker. In order to build a symbol table, you must omit the
|
|
\&\fBS\fR modifier on the last execution of \fBar\fR, or you must run
|
|
\&\fBranlib\fR on the archive.
|
|
.IP \fBT\fR 4
|
|
.IX Item "T"
|
|
Deprecated alias for \fB\-\-thin\fR. \fBT\fR is not recommended because in
|
|
many ar implementations \fBT\fR has a different meaning, as specified by
|
|
X/Open System Interface.
|
|
.IP \fBu\fR 4
|
|
.IX Item "u"
|
|
Normally, \fBar r\fR... inserts all files
|
|
listed into the archive. If you would like to insert \fIonly\fR those
|
|
of the files you list that are newer than existing members of the same
|
|
names, use this modifier. The \fBu\fR modifier is allowed only for the
|
|
operation \fBr\fR (replace). In particular, the combination \fBqu\fR is
|
|
not allowed, since checking the timestamps would lose any speed
|
|
advantage from the operation \fBq\fR.
|
|
.IP \fBU\fR 4
|
|
.IX Item "U"
|
|
Do \fInot\fR operate in \fIdeterministic\fR mode. This is the inverse
|
|
of the \fBD\fR modifier, above: added files and the archive index will
|
|
get their actual UID, GID, timestamp, and file mode values.
|
|
.Sp
|
|
This is the default unless \fIbinutils\fR was configured with
|
|
\&\fB\-\-enable\-deterministic\-archives\fR.
|
|
.IP \fBv\fR 4
|
|
.IX Item "v"
|
|
This modifier requests the \fIverbose\fR version of an operation. Many
|
|
operations display additional information, such as filenames processed,
|
|
when the modifier \fBv\fR is appended.
|
|
.IP \fBV\fR 4
|
|
.IX Item "V"
|
|
This modifier shows the version number of \fBar\fR.
|
|
.PP
|
|
The \fBar\fR program also supports some command-line options which
|
|
are neither modifiers nor actions, but which do change its behaviour
|
|
in specific ways:
|
|
.IP \fB\-\-help\fR 4
|
|
.IX Item "--help"
|
|
Displays the list of command-line options supported by \fBar\fR
|
|
and then exits.
|
|
.IP \fB\-\-version\fR 4
|
|
.IX Item "--version"
|
|
Displays the version information of \fBar\fR and then exits.
|
|
.IP \fB\-X32_64\fR 4
|
|
.IX Item "-X32_64"
|
|
\&\fBar\fR ignores an initial option spelled \fB\-X32_64\fR, for
|
|
compatibility with AIX. The behaviour produced by this option is the
|
|
default for GNU \fBar\fR. \fBar\fR does not support any
|
|
of the other \fB\-X\fR options; in particular, it does not support
|
|
\&\fB\-X32\fR which is the default for AIX \fBar\fR.
|
|
.IP "\fB\-\-plugin\fR \fIname\fR" 4
|
|
.IX Item "--plugin name"
|
|
The optional command-line switch \fB\-\-plugin\fR \fIname\fR causes
|
|
\&\fBar\fR to load the plugin called \fIname\fR which adds support
|
|
for more file formats, including object files with link-time
|
|
optimization information.
|
|
.Sp
|
|
This option is only available if the toolchain has been built with
|
|
plugin support enabled.
|
|
.Sp
|
|
If \fB\-\-plugin\fR is not provided, but plugin support has been
|
|
enabled then \fBar\fR iterates over the files in
|
|
\&\fI${libdir}/bfd\-plugins\fR in alphabetic order and the first
|
|
plugin that claims the object in question is used.
|
|
.Sp
|
|
Please note that this plugin search directory is \fInot\fR the one
|
|
used by \fBld\fR's \fB\-plugin\fR option. In order to make
|
|
\&\fBar\fR use the linker plugin it must be copied into the
|
|
\&\fI${libdir}/bfd\-plugins\fR directory. For GCC based compilations
|
|
the linker plugin is called \fIliblto_plugin.so.0.0.0\fR. For Clang
|
|
based compilations it is called \fILLVMgold.so\fR. The GCC plugin
|
|
is always backwards compatible with earlier versions, so it is
|
|
sufficient to just copy the newest one.
|
|
.IP "\fB\-\-target\fR \fItarget\fR" 4
|
|
.IX Item "--target target"
|
|
The optional command-line switch \fB\-\-target\fR \fIbfdname\fR
|
|
specifies that the archive members are in an object code format
|
|
different from your system's default format. See
|
|
.IP "\fB\-\-output\fR \fIdirname\fR" 4
|
|
.IX Item "--output dirname"
|
|
The \fB\-\-output\fR option can be used to specify a path to a
|
|
directory into which archive members should be extracted. If this
|
|
option is not specified then the current directory will be used.
|
|
.Sp
|
|
Note \- although the presence of this option does imply a \fBx\fR
|
|
extraction operation that option must still be included on the command
|
|
line.
|
|
.IP "\fB\-\-record\-libdeps\fR \fIlibdeps\fR" 4
|
|
.IX Item "--record-libdeps libdeps"
|
|
The \fB\-\-record\-libdeps\fR option is identical to the \fBl\fR modifier,
|
|
just handled in long form.
|
|
.IP \fB\-\-thin\fR 4
|
|
.IX Item "--thin"
|
|
Make the specified \fIarchive\fR a \fIthin\fR archive. If it already
|
|
exists and is a regular archive, the existing members must be present
|
|
in the same directory as \fIarchive\fR.
|
|
.IP \fB@\fR\fIfile\fR 4
|
|
.IX Item "@file"
|
|
Read command-line options from \fIfile\fR. The options read are
|
|
inserted in place of the original @\fIfile\fR option. If \fIfile\fR
|
|
does not exist, or cannot be read, then the option will be treated
|
|
literally, and not removed.
|
|
.Sp
|
|
Options in \fIfile\fR are separated by whitespace. A whitespace
|
|
character may be included in an option by surrounding the entire
|
|
option in either single or double quotes. Any character (including a
|
|
backslash) may be included by prefixing the character to be included
|
|
with a backslash. The \fIfile\fR may itself contain additional
|
|
@\fIfile\fR options; any such options will be processed recursively.
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
\&\fBnm\fR\|(1), \fBranlib\fR\|(1), and the Info entries for \fIbinutils\fR.
|
|
.SH COPYRIGHT
|
|
.IX Header "COPYRIGHT"
|
|
Copyright (c) 1991\-2023 Free Software Foundation, Inc.
|
|
.PP
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3
|
|
or any later version published by the Free Software Foundation;
|
|
with no Invariant Sections, with no Front-Cover Texts, and with no
|
|
Back-Cover Texts. A copy of the license is included in the
|
|
section entitled "GNU Free Documentation License".
|