588 lines
18 KiB
HTML
588 lines
18 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of AR</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>AR</H1>
|
|
Section: GNU Development Tools (1)<BR>Updated: 2021-01-21<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
ar - create, modify, and extract from archives
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
ar [<B>-X32_64</B>] [<B>-</B>]<I>p</I>[<I>mod</I>] [<B>--plugin</B> <I>name</I>] [<B>--target</B> <I>bfdname</I>] [<B>--output</B> <I>dirname</I>] [<I>relpos</I>] [<I>count</I>] <I>archive</I> [<I>member</I>...]
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
The <FONT SIZE="-1">GNU</FONT> <B>ar</B> program creates, modifies, and extracts from
|
|
archives. An <I>archive</I> is a single file holding a collection of
|
|
other files in a structure that makes it possible to retrieve
|
|
the original individual files (called <I>members</I> of the archive).
|
|
<P>
|
|
|
|
The original files' contents, mode (permissions), timestamp, owner, and
|
|
group are preserved in the archive, and can be restored on
|
|
extraction.
|
|
<P>
|
|
|
|
<FONT SIZE="-1">GNU</FONT> <B>ar</B> can maintain archives whose members have names of any
|
|
length; however, depending on how <B>ar</B> 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).
|
|
<P>
|
|
|
|
<B>ar</B> is considered a binary utility because archives of this sort
|
|
are most often used as <I>libraries</I> holding commonly needed
|
|
subroutines.
|
|
<P>
|
|
|
|
<B>ar</B> creates an index to the symbols defined in relocatable
|
|
object modules in the archive when you specify the modifier <B>s</B>.
|
|
Once created, this index is updated in the archive whenever <B>ar</B>
|
|
makes a change to its contents (save for the <B>q</B> 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.
|
|
<P>
|
|
|
|
You may use <B>nm -s</B> or <B>nm --print-armap</B> to list this index
|
|
table. If an archive lacks the table, another form of <B>ar</B> called
|
|
<B>ranlib</B> can be used to add just the table.
|
|
<P>
|
|
|
|
<FONT SIZE="-1">GNU</FONT> <B>ar</B> can optionally create a <I>thin</I> 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.
|
|
<P>
|
|
|
|
An archive can either be <I>thin</I> 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.
|
|
<P>
|
|
|
|
Thin archives are also <I>flattened</I>, 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.
|
|
<P>
|
|
|
|
The paths to the elements of the archive are stored relative to the
|
|
archive itself.
|
|
<P>
|
|
|
|
<FONT SIZE="-1">GNU</FONT> <B>ar</B> is designed to be compatible with two different
|
|
facilities. You can control its activity using command-line options,
|
|
like the different varieties of <B>ar</B> on Unix systems; or, if you
|
|
specify the single command-line option <B>-M</B>, you can control it
|
|
with a script supplied via standard input, like the <FONT SIZE="-1">MRI</FONT> ``librarian''
|
|
program.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
|
|
|
|
<FONT SIZE="-1">GNU</FONT> <B>ar</B> allows you to mix the operation code <I>p</I> and modifier
|
|
flags <I>mod</I> in any order, within the first command-line argument.
|
|
<P>
|
|
|
|
If you wish, you may begin the first command-line argument with a
|
|
dash.
|
|
<P>
|
|
|
|
The <I>p</I> keyletter specifies what operation to execute; it may be
|
|
any of the following, but you must specify only one of them:
|
|
<DL COMPACT>
|
|
<DT id="1"><B>d</B><DD>
|
|
|
|
|
|
<I>Delete</I> modules from the archive. Specify the names of modules to
|
|
be deleted as <I>member</I>...; the archive is untouched if you
|
|
specify no files to delete.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you specify the <B>v</B> modifier, <B>ar</B> lists each module
|
|
as it is deleted.
|
|
<DT id="2"><B>m</B><DD>
|
|
|
|
|
|
Use this operation to <I>move</I> members in an archive.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If no modifiers are used with <TT>"m"</TT>, any members you name in the
|
|
<I>member</I> arguments are moved to the <I>end</I> of the archive;
|
|
you can use the <B>a</B>, <B>b</B>, or <B>i</B> modifiers to move them to a
|
|
specified place instead.
|
|
<DT id="3"><B>p</B><DD>
|
|
|
|
|
|
<I>Print</I> the specified members of the archive, to the standard
|
|
output file. If the <B>v</B> modifier is specified, show the member
|
|
name before copying its contents to standard output.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you specify no <I>member</I> arguments, all the files in the archive are
|
|
printed.
|
|
<DT id="4"><B>q</B><DD>
|
|
|
|
|
|
<I>Quick append</I>; Historically, add the files <I>member</I>... to the end of
|
|
<I>archive</I>, without checking for replacement.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The modifiers <B>a</B>, <B>b</B>, and <B>i</B> do <I>not</I> affect this
|
|
operation; new members are always placed at the end of the archive.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The modifier <B>v</B> makes <B>ar</B> list each file as it is appended.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Since the point of this operation is speed, implementations of
|
|
<B>ar</B> 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 <FONT SIZE="-1">GNU</FONT> <B>ar</B> will
|
|
rebuild the table even with a quick append.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note - <FONT SIZE="-1">GNU</FONT> <B>ar</B> treats the command <B>qs</B> as a
|
|
synonym for <B>r</B> - replacing already existing files in the
|
|
archive and appending new ones at the end.
|
|
<DT id="5"><B>r</B><DD>
|
|
|
|
|
|
Insert the files <I>member</I>... into <I>archive</I> (with
|
|
<I>replacement</I>). This operation differs from <B>q</B> in that any
|
|
previously existing members are deleted if their names match those being
|
|
added.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If one of the files named in <I>member</I>... does not exist, <B>ar</B>
|
|
displays an error message, and leaves undisturbed any existing members
|
|
of the archive matching that name.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
By default, new members are added at the end of the file; but you may
|
|
use one of the modifiers <B>a</B>, <B>b</B>, or <B>i</B> to request
|
|
placement relative to some existing member.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The modifier <B>v</B> used with this operation elicits a line of
|
|
output for each file inserted, along with one of the letters <B>a</B> or
|
|
<B>r</B> to indicate whether the file was appended (no old member
|
|
deleted) or replaced.
|
|
<DT id="6"><B>s</B><DD>
|
|
|
|
|
|
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.
|
|
<DT id="7"><B>t</B><DD>
|
|
|
|
|
|
Display a <I>table</I> listing the contents of <I>archive</I>, or those
|
|
of the files listed in <I>member</I>... that are present in the
|
|
archive. Normally only the member name is shown, but if the modifier
|
|
<B>O</B> 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 <B>v</B> modifier should be included.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you do not specify a <I>member</I>, all files in the archive
|
|
are listed.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If there is more than one file with the same name (say, <B>fie</B>) in
|
|
an archive (say <B>b.a</B>), <B>ar t b.a fie</B> lists only the
|
|
first instance; to see them all, you must ask for a complete
|
|
listing---in our example, <B>ar t b.a</B>.
|
|
<DT id="8"><B>x</B><DD>
|
|
|
|
|
|
<I>Extract</I> members (named <I>member</I>) from the archive. You can
|
|
use the <B>v</B> modifier with this operation, to request that
|
|
<B>ar</B> list each name as it extracts it.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you do not specify a <I>member</I>, all files in the archive
|
|
are extracted.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Files cannot be extracted from a thin archive, and there are
|
|
restrictions on extracting from archives created with <B>P</B>: The
|
|
paths must not be absolute, may not contain <TT>".."</TT>, and any
|
|
subdirectories in the paths must exist. If it is desired to avoid
|
|
these restrictions then used the <B>--output</B> option to specify
|
|
an output directory.
|
|
</DL>
|
|
<P>
|
|
|
|
A number of modifiers (<I>mod</I>) may immediately follow the <I>p</I>
|
|
keyletter, to specify variations on an operation's behavior:
|
|
<DL COMPACT>
|
|
<DT id="9"><B>a</B><DD>
|
|
|
|
|
|
Add new files <I>after</I> an existing member of the
|
|
archive. If you use the modifier <B>a</B>, the name of an existing archive
|
|
member must be present as the <I>relpos</I> argument, before the
|
|
<I>archive</I> specification.
|
|
<DT id="10"><B>b</B><DD>
|
|
|
|
|
|
Add new files <I>before</I> an existing member of the
|
|
archive. If you use the modifier <B>b</B>, the name of an existing archive
|
|
member must be present as the <I>relpos</I> argument, before the
|
|
<I>archive</I> specification. (same as <B>i</B>).
|
|
<DT id="11"><B>c</B><DD>
|
|
|
|
|
|
<I>Create</I> the archive. The specified <I>archive</I> 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.
|
|
<DT id="12"><B>D</B><DD>
|
|
|
|
|
|
Operate in <I>deterministic</I> 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 <B>ar</B> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If <I>binutils</I> was configured with
|
|
<B>--enable-deterministic-archives</B>, then this mode is on by default.
|
|
It can be disabled with the <B>U</B> modifier, below.
|
|
<DT id="13"><B>f</B><DD>
|
|
|
|
|
|
Truncate names in the archive. <FONT SIZE="-1">GNU</FONT> <B>ar</B> will normally permit file
|
|
names of any length. This will cause it to create archives which are
|
|
not compatible with the native <B>ar</B> program on some systems. If
|
|
this is a concern, the <B>f</B> modifier may be used to truncate file
|
|
names when putting them in the archive.
|
|
<DT id="14"><B>i</B><DD>
|
|
|
|
|
|
Insert new files <I>before</I> an existing member of the
|
|
archive. If you use the modifier <B>i</B>, the name of an existing archive
|
|
member must be present as the <I>relpos</I> argument, before the
|
|
<I>archive</I> specification. (same as <B>b</B>).
|
|
<DT id="15"><B>l</B><DD>
|
|
|
|
|
|
This modifier is accepted but not used.
|
|
<DT id="16"><B>N</B><DD>
|
|
|
|
|
|
Uses the <I>count</I> parameter. This is used if there are multiple
|
|
entries in the archive with the same name. Extract or delete instance
|
|
<I>count</I> of the given name from the archive.
|
|
<DT id="17"><B>o</B><DD>
|
|
|
|
|
|
Preserve the <I>original</I> 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.
|
|
<DT id="18"><B>O</B><DD>
|
|
|
|
|
|
Display member offsets inside the archive. Use together with the <B>t</B>
|
|
option.
|
|
<DT id="19"><B>P</B><DD>
|
|
|
|
|
|
Use the full path name when matching or storing names in the archive.
|
|
Archives created with full path names are not <FONT SIZE="-1">POSIX</FONT> compliant, and
|
|
thus may not work with tools other than up to date <FONT SIZE="-1">GNU</FONT> tools.
|
|
Modifying such archives with <FONT SIZE="-1">GNU</FONT> <B>ar</B> without using
|
|
<B>P</B> will remove the full path names unless the archive is a
|
|
thin archive. Note that <B>P</B> may be useful when adding files to
|
|
a thin archive since <B>r</B> without <B>P</B> ignores the path
|
|
when choosing which element to replace. Thus
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
ar rcST archive.a subdir/file1 subdir/file2 file1
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
will result in the first <TT>"subdir/file1"</TT> being replaced with
|
|
<TT>"file1"</TT> from the current directory. Adding <B>P</B> will
|
|
prevent this replacement.
|
|
<DT id="20"><B>s</B><DD>
|
|
|
|
|
|
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 <B>ar s</B> on an
|
|
archive is equivalent to running <B>ranlib</B> on it.
|
|
<DT id="21"><B>S</B><DD>
|
|
|
|
|
|
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
|
|
<B>S</B> modifier on the last execution of <B>ar</B>, or you must run
|
|
<B>ranlib</B> on the archive.
|
|
<DT id="22"><B>T</B><DD>
|
|
|
|
|
|
Make the specified <I>archive</I> a <I>thin</I> archive. If it already
|
|
exists and is a regular archive, the existing members must be present
|
|
in the same directory as <I>archive</I>.
|
|
<DT id="23"><B>u</B><DD>
|
|
|
|
|
|
Normally, <B>ar r</B>... inserts all files
|
|
listed into the archive. If you would like to insert <I>only</I> those
|
|
of the files you list that are newer than existing members of the same
|
|
names, use this modifier. The <B>u</B> modifier is allowed only for the
|
|
operation <B>r</B> (replace). In particular, the combination <B>qu</B> is
|
|
not allowed, since checking the timestamps would lose any speed
|
|
advantage from the operation <B>q</B>.
|
|
<DT id="24"><B>U</B><DD>
|
|
|
|
|
|
Do <I>not</I> operate in <I>deterministic</I> mode. This is the inverse
|
|
of the <B>D</B> modifier, above: added files and the archive index will
|
|
get their actual <FONT SIZE="-1">UID, GID,</FONT> timestamp, and file mode values.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This is the default unless <I>binutils</I> was configured with
|
|
<B>--enable-deterministic-archives</B>.
|
|
<DT id="25"><B>v</B><DD>
|
|
|
|
|
|
This modifier requests the <I>verbose</I> version of an operation. Many
|
|
operations display additional information, such as filenames processed,
|
|
when the modifier <B>v</B> is appended.
|
|
<DT id="26"><B>V</B><DD>
|
|
|
|
|
|
This modifier shows the version number of <B>ar</B>.
|
|
</DL>
|
|
<P>
|
|
|
|
The <B>ar</B> program also supports some command-line options which
|
|
are neither modifiers nor actions, but which do change its behaviour
|
|
in specific ways:
|
|
<DL COMPACT>
|
|
<DT id="27"><B>--help</B><DD>
|
|
|
|
|
|
Displays the list of command-line options supported by <B>ar</B>
|
|
and then exits.
|
|
<DT id="28"><B>--version</B><DD>
|
|
|
|
|
|
Displays the version information of <B>ar</B> and then exits.
|
|
<DT id="29"><B>-X32_64</B><DD>
|
|
|
|
|
|
<B>ar</B> ignores an initial option spelled <B>-X32_64</B>, for
|
|
compatibility with <FONT SIZE="-1">AIX.</FONT> The behaviour produced by this option is the
|
|
default for <FONT SIZE="-1">GNU</FONT> <B>ar</B>. <B>ar</B> does not support any
|
|
of the other <B>-X</B> options; in particular, it does not support
|
|
<B>-X32</B> which is the default for <FONT SIZE="-1">AIX</FONT> <B>ar</B>.
|
|
<DT id="30"><B>--plugin</B> <I>name</I><DD>
|
|
|
|
|
|
The optional command-line switch <B>--plugin</B> <I>name</I> causes
|
|
<B>ar</B> to load the plugin called <I>name</I> which adds support
|
|
for more file formats, including object files with link-time
|
|
optimization information.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option is only available if the toolchain has been built with
|
|
plugin support enabled.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If <B>--plugin</B> is not provided, but plugin support has been
|
|
enabled then <B>ar</B> iterates over the files in
|
|
<I>${libdir}/bfd-plugins</I> in alphabetic order and the first
|
|
plugin that claims the object in question is used.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Please note that this plugin search directory is <I>not</I> the one
|
|
used by <B>ld</B>'s <B>-plugin</B> option. In order to make
|
|
<B>ar</B> use the linker plugin it must be copied into the
|
|
<I>${libdir}/bfd-plugins</I> directory. For <FONT SIZE="-1">GCC</FONT> based compilations
|
|
the linker plugin is called <I>liblto_plugin.so.0.0.0</I>. For Clang
|
|
based compilations it is called <I>LLVMgold.so</I>. The <FONT SIZE="-1">GCC</FONT> plugin
|
|
is always backwards compatible with earlier versions, so it is
|
|
sufficient to just copy the newest one.
|
|
<DT id="31"><B>--target</B> <I>target</I><DD>
|
|
|
|
|
|
The optional command-line switch <B>--target</B> <I>bfdname</I>
|
|
specifies that the archive members are in an object code format
|
|
different from your system's default format. See
|
|
<DT id="32"><B>--output</B> <I>dirname</I><DD>
|
|
|
|
|
|
The <B>--output</B> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note - although the presence of this option does imply a <B>x</B>
|
|
extraction operation that option must still be included on the command
|
|
line.
|
|
<DT id="33"><B>@</B><I>file</I><DD>
|
|
|
|
|
|
Read command-line options from <I>file</I>. The options read are
|
|
inserted in place of the original @<I>file</I> option. If <I>file</I>
|
|
does not exist, or cannot be read, then the option will be treated
|
|
literally, and not removed.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Options in <I>file</I> 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 <I>file</I> may itself contain additional
|
|
@<I>file</I> options; any such options will be processed recursively.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+nm">nm</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+ranlib">ranlib</A></B>(1), and the Info entries for <I>binutils</I>.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>COPYRIGHT</H2>
|
|
|
|
|
|
|
|
Copyright (c) 1991-2020 Free Software Foundation, Inc.
|
|
<P>
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the <FONT SIZE="-1">GNU</FONT> 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 ``<FONT SIZE="-1">GNU</FONT> Free Documentation License''.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="34"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="35"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="36"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="37"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DT id="38"><A HREF="#lbAF">SEE ALSO</A><DD>
|
|
<DT id="39"><A HREF="#lbAG">COPYRIGHT</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:07 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|