You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
283 lines
19 KiB
HTML
283 lines
19 KiB
HTML
<html lang="en">
|
|
<head>
|
|
<title>ar cmdline - GNU Binary Utilities</title>
|
|
<meta http-equiv="Content-Type" content="text/html">
|
|
<meta name="description" content="GNU Binary Utilities">
|
|
<meta name="generator" content="makeinfo 4.13">
|
|
<link title="Top" rel="start" href="index.html#Top">
|
|
<link rel="up" href="ar.html#ar" title="ar">
|
|
<link rel="next" href="ar-scripts.html#ar-scripts" title="ar scripts">
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
|
<!--
|
|
Copyright (C) 1991-2015 Free Software Foundation, Inc.
|
|
|
|
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''.
|
|
|
|
-->
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
|
<style type="text/css"><!--
|
|
pre.display { font-family:inherit }
|
|
pre.format { font-family:inherit }
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
|
pre.smallexample { font-size:smaller }
|
|
pre.smalllisp { font-size:smaller }
|
|
span.sc { font-variant:small-caps }
|
|
span.roman { font-family:serif; font-weight:normal; }
|
|
span.sansserif { font-family:sans-serif; font-weight:normal; }
|
|
--></style>
|
|
</head>
|
|
<body>
|
|
<div class="node">
|
|
<a name="ar-cmdline"></a>
|
|
<p>
|
|
Next: <a rel="next" accesskey="n" href="ar-scripts.html#ar-scripts">ar scripts</a>,
|
|
Up: <a rel="up" accesskey="u" href="ar.html#ar">ar</a>
|
|
<hr>
|
|
</div>
|
|
|
|
<h3 class="section">1.1 Controlling <samp><span class="command">ar</span></samp> on the Command Line</h3>
|
|
|
|
<pre class="smallexample"> <!-- man begin SYNOPSIS ar -->
|
|
ar [<samp><span class="option">-X32_64</span></samp>] [<samp><span class="option">-</span></samp>]<var>p</var>[<var>mod</var>] [<samp><span class="option">--plugin</span></samp> <var>name</var>] [<samp><span class="option">--target</span></samp> <var>bfdname</var>] [<var>relpos</var>] [<var>count</var>] <var>archive</var> [<var>member</var>...]
|
|
<!-- man end -->
|
|
</pre>
|
|
<p><a name="index-Unix-compatibility_002c-_0040command_007bar_007d-11"></a>When you use <samp><span class="command">ar</span></samp> in the Unix style, <samp><span class="command">ar</span></samp> insists on at least two
|
|
arguments to execute: one keyletter specifying the <em>operation</em>
|
|
(optionally accompanied by other keyletters specifying
|
|
<em>modifiers</em>), and the archive name to act on.
|
|
|
|
<p>Most operations can also accept further <var>member</var> arguments,
|
|
specifying particular files to operate on.
|
|
|
|
<!-- man begin OPTIONS ar -->
|
|
<p><span class="sc">gnu</span> <samp><span class="command">ar</span></samp> allows you to mix the operation code <var>p</var> and modifier
|
|
flags <var>mod</var> 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><a name="index-operations-on-archive-12"></a>The <var>p</var> keyletter specifies what operation to execute; it may be
|
|
any of the following, but you must specify only one of them:
|
|
|
|
<dl>
|
|
<dt>‘<samp><span class="samp">d</span></samp>’<dd><a name="index-deleting-from-archive-13"></a><em>Delete</em> modules from the archive. Specify the names of modules to
|
|
be deleted as <var>member</var><small class="dots">...</small>; the archive is untouched if you
|
|
specify no files to delete.
|
|
|
|
<p>If you specify the ‘<samp><span class="samp">v</span></samp>’ modifier, <samp><span class="command">ar</span></samp> lists each module
|
|
as it is deleted.
|
|
|
|
<br><dt>‘<samp><span class="samp">m</span></samp>’<dd><a name="index-moving-in-archive-14"></a>Use this operation to <em>move</em> 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 <code>m</code>, any members you name in the
|
|
<var>member</var> arguments are moved to the <em>end</em> of the archive;
|
|
you can use the ‘<samp><span class="samp">a</span></samp>’, ‘<samp><span class="samp">b</span></samp>’, or ‘<samp><span class="samp">i</span></samp>’ modifiers to move them to a
|
|
specified place instead.
|
|
|
|
<br><dt>‘<samp><span class="samp">p</span></samp>’<dd><a name="index-printing-from-archive-15"></a><em>Print</em> the specified members of the archive, to the standard
|
|
output file. If the ‘<samp><span class="samp">v</span></samp>’ modifier is specified, show the member
|
|
name before copying its contents to standard output.
|
|
|
|
<p>If you specify no <var>member</var> arguments, all the files in the archive are
|
|
printed.
|
|
|
|
<br><dt>‘<samp><span class="samp">q</span></samp>’<dd><a name="index-quick-append-to-archive-16"></a><em>Quick append</em>; Historically, add the files <var>member</var><small class="dots">...</small> to the end of
|
|
<var>archive</var>, without checking for replacement.
|
|
|
|
<p>The modifiers ‘<samp><span class="samp">a</span></samp>’, ‘<samp><span class="samp">b</span></samp>’, and ‘<samp><span class="samp">i</span></samp>’ do <em>not</em> affect this
|
|
operation; new members are always placed at the end of the archive.
|
|
|
|
<p>The modifier ‘<samp><span class="samp">v</span></samp>’ makes <samp><span class="command">ar</span></samp> list each file as it is appended.
|
|
|
|
<p>Since the point of this operation is speed, implementations of
|
|
<samp><span class="command">ar</span></samp> 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 <span class="sc">gnu</span> <samp><span class="command">ar</span></samp> will
|
|
rebuild the table even with a quick append.
|
|
|
|
<p>Note - <span class="sc">gnu</span> <samp><span class="command">ar</span></samp> treats the command ‘<samp><span class="samp">qs</span></samp>’ as a
|
|
synonym for ‘<samp><span class="samp">r</span></samp>’ - replacing already existing files in the
|
|
archive and appending new ones at the end.
|
|
|
|
<br><dt>‘<samp><span class="samp">r</span></samp>’<dd><a name="index-replacement-in-archive-17"></a>Insert the files <var>member</var><small class="dots">...</small> into <var>archive</var> (with
|
|
<em>replacement</em>). This operation differs from ‘<samp><span class="samp">q</span></samp>’ in that any
|
|
previously existing members are deleted if their names match those being
|
|
added.
|
|
|
|
<p>If one of the files named in <var>member</var><small class="dots">...</small> does not exist, <samp><span class="command">ar</span></samp>
|
|
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 ‘<samp><span class="samp">a</span></samp>’, ‘<samp><span class="samp">b</span></samp>’, or ‘<samp><span class="samp">i</span></samp>’ to request
|
|
placement relative to some existing member.
|
|
|
|
<p>The modifier ‘<samp><span class="samp">v</span></samp>’ used with this operation elicits a line of
|
|
output for each file inserted, along with one of the letters ‘<samp><span class="samp">a</span></samp>’ or
|
|
‘<samp><span class="samp">r</span></samp>’ to indicate whether the file was appended (no old member
|
|
deleted) or replaced.
|
|
|
|
<br><dt>‘<samp><span class="samp">s</span></samp>’<dd><a name="index-ranlib-18"></a>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.
|
|
|
|
<br><dt>‘<samp><span class="samp">t</span></samp>’<dd><a name="index-contents-of-archive-19"></a>Display a <em>table</em> listing the contents of <var>archive</var>, or those
|
|
of the files listed in <var>member</var><small class="dots">...</small> that are present in the
|
|
archive. Normally only the member name is shown; if you also want to
|
|
see the modes (permissions), timestamp, owner, group, and size, you can
|
|
request that by also specifying the ‘<samp><span class="samp">v</span></samp>’ modifier.
|
|
|
|
<p>If you do not specify a <var>member</var>, all files in the archive
|
|
are listed.
|
|
|
|
<p><a name="index-repeated-names-in-archive-20"></a><a name="index-name-duplication-in-archive-21"></a>If there is more than one file with the same name (say, ‘<samp><span class="samp">fie</span></samp>’) in
|
|
an archive (say ‘<samp><span class="samp">b.a</span></samp>’), ‘<samp><span class="samp">ar t b.a fie</span></samp>’ lists only the
|
|
first instance; to see them all, you must ask for a complete
|
|
listing—in our example, ‘<samp><span class="samp">ar t b.a</span></samp>’.
|
|
<!-- WRS only; per Gumby, this is implementation-dependent, and in a more -->
|
|
<!-- recent case in fact works the other way. -->
|
|
|
|
<br><dt>‘<samp><span class="samp">x</span></samp>’<dd><a name="index-extract-from-archive-22"></a><em>Extract</em> members (named <var>member</var>) from the archive. You can
|
|
use the ‘<samp><span class="samp">v</span></samp>’ modifier with this operation, to request that
|
|
<samp><span class="command">ar</span></samp> list each name as it extracts it.
|
|
|
|
<p>If you do not specify a <var>member</var>, all files in the archive
|
|
are extracted.
|
|
|
|
<p>Files cannot be extracted from a thin archive.
|
|
|
|
<br><dt>‘<samp><span class="samp">--help</span></samp>’<dd>Displays the list of command line options supported by <samp><span class="command">ar</span></samp>
|
|
and then exits.
|
|
|
|
<br><dt>‘<samp><span class="samp">--version</span></samp>’<dd>Displays the version information of <samp><span class="command">ar</span></samp> and then exits.
|
|
|
|
</dl>
|
|
|
|
<p>A number of modifiers (<var>mod</var>) may immediately follow the <var>p</var>
|
|
keyletter, to specify variations on an operation's behavior:
|
|
|
|
<dl>
|
|
<dt>‘<samp><span class="samp">a</span></samp>’<dd><a name="index-relative-placement-in-archive-23"></a>Add new files <em>after</em> an existing member of the
|
|
archive. If you use the modifier ‘<samp><span class="samp">a</span></samp>’, the name of an existing archive
|
|
member must be present as the <var>relpos</var> argument, before the
|
|
<var>archive</var> specification.
|
|
|
|
<br><dt>‘<samp><span class="samp">b</span></samp>’<dd>Add new files <em>before</em> an existing member of the
|
|
archive. If you use the modifier ‘<samp><span class="samp">b</span></samp>’, the name of an existing archive
|
|
member must be present as the <var>relpos</var> argument, before the
|
|
<var>archive</var> specification. (same as ‘<samp><span class="samp">i</span></samp>’).
|
|
|
|
<br><dt>‘<samp><span class="samp">c</span></samp>’<dd><a name="index-creating-archives-24"></a><em>Create</em> the archive. The specified <var>archive</var> 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.
|
|
|
|
<br><dt>‘<samp><span class="samp">D</span></samp>’<dd><a name="index-deterministic-archives-25"></a><a name="index-g_t_002d_002denable_002ddeterministic_002darchives-26"></a>Operate in <em>deterministic</em> 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 <samp><span class="command">ar</span></samp> 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 <samp><span class="file">binutils</span></samp> was configured with
|
|
<samp><span class="option">--enable-deterministic-archives</span></samp>, then this mode is on by default.
|
|
It can be disabled with the ‘<samp><span class="samp">U</span></samp>’ modifier, below.
|
|
|
|
<br><dt>‘<samp><span class="samp">f</span></samp>’<dd>Truncate names in the archive. <span class="sc">gnu</span> <samp><span class="command">ar</span></samp> will normally permit file
|
|
names of any length. This will cause it to create archives which are
|
|
not compatible with the native <samp><span class="command">ar</span></samp> program on some systems. If
|
|
this is a concern, the ‘<samp><span class="samp">f</span></samp>’ modifier may be used to truncate file
|
|
names when putting them in the archive.
|
|
|
|
<br><dt>‘<samp><span class="samp">i</span></samp>’<dd>Insert new files <em>before</em> an existing member of the
|
|
archive. If you use the modifier ‘<samp><span class="samp">i</span></samp>’, the name of an existing archive
|
|
member must be present as the <var>relpos</var> argument, before the
|
|
<var>archive</var> specification. (same as ‘<samp><span class="samp">b</span></samp>’).
|
|
|
|
<br><dt>‘<samp><span class="samp">l</span></samp>’<dd>This modifier is accepted but not used.
|
|
<!-- whaffor ar l modifier??? presumably compat; with -->
|
|
<!-- what???-doc@@cygnus.com, 25jan91 -->
|
|
|
|
<br><dt>‘<samp><span class="samp">N</span></samp>’<dd>Uses the <var>count</var> parameter. This is used if there are multiple
|
|
entries in the archive with the same name. Extract or delete instance
|
|
<var>count</var> of the given name from the archive.
|
|
|
|
<br><dt>‘<samp><span class="samp">o</span></samp>’<dd><a name="index-dates-in-archive-27"></a>Preserve the <em>original</em> 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.
|
|
|
|
<br><dt>‘<samp><span class="samp">P</span></samp>’<dd>Use the full path name when matching names in the archive. <span class="sc">gnu</span>
|
|
<samp><span class="command">ar</span></samp> can not create an archive with a full path name (such archives
|
|
are not POSIX complaint), but other archive creators can. This option
|
|
will cause <span class="sc">gnu</span> <samp><span class="command">ar</span></samp> to match file names using a complete path
|
|
name, which can be convenient when extracting a single file from an
|
|
archive created by another tool.
|
|
|
|
<br><dt>‘<samp><span class="samp">s</span></samp>’<dd><a name="index-writing-archive-index-28"></a>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 ‘<samp><span class="samp">ar s</span></samp>’ on an
|
|
archive is equivalent to running ‘<samp><span class="samp">ranlib</span></samp>’ on it.
|
|
|
|
<br><dt>‘<samp><span class="samp">S</span></samp>’<dd><a name="index-not-writing-archive-index-29"></a>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
|
|
‘<samp><span class="samp">S</span></samp>’ modifier on the last execution of ‘<samp><span class="samp">ar</span></samp>’, or you must run
|
|
‘<samp><span class="samp">ranlib</span></samp>’ on the archive.
|
|
|
|
<br><dt>‘<samp><span class="samp">T</span></samp>’<dd><a name="index-creating-thin-archive-30"></a>Make the specified <var>archive</var> a <em>thin</em> archive. If it already
|
|
exists and is a regular archive, the existing members must be present
|
|
in the same directory as <var>archive</var>.
|
|
|
|
<br><dt>‘<samp><span class="samp">u</span></samp>’<dd><a name="index-updating-an-archive-31"></a>Normally, ‘<samp><span class="samp">ar r</span></samp>’<small class="dots">...</small> inserts all files
|
|
listed into the archive. If you would like to insert <em>only</em> those
|
|
of the files you list that are newer than existing members of the same
|
|
names, use this modifier. The ‘<samp><span class="samp">u</span></samp>’ modifier is allowed only for the
|
|
operation ‘<samp><span class="samp">r</span></samp>’ (replace). In particular, the combination ‘<samp><span class="samp">qu</span></samp>’ is
|
|
not allowed, since checking the timestamps would lose any speed
|
|
advantage from the operation ‘<samp><span class="samp">q</span></samp>’.
|
|
|
|
<br><dt>‘<samp><span class="samp">U</span></samp>’<dd><a name="index-deterministic-archives-32"></a><a name="index-g_t_002d_002denable_002ddeterministic_002darchives-33"></a>Do <em>not</em> operate in <em>deterministic</em> mode. This is the inverse
|
|
of the ‘<samp><span class="samp">D</span></samp>’ modifier, above: added files and the archive index will
|
|
get their actual UID, GID, timestamp, and file mode values.
|
|
|
|
<p>This is the default unless <samp><span class="file">binutils</span></samp> was configured with
|
|
<samp><span class="option">--enable-deterministic-archives</span></samp>.
|
|
|
|
<br><dt>‘<samp><span class="samp">v</span></samp>’<dd>This modifier requests the <em>verbose</em> version of an operation. Many
|
|
operations display additional information, such as filenames processed,
|
|
when the modifier ‘<samp><span class="samp">v</span></samp>’ is appended.
|
|
|
|
<br><dt>‘<samp><span class="samp">V</span></samp>’<dd>This modifier shows the version number of <samp><span class="command">ar</span></samp>.
|
|
</dl>
|
|
|
|
<p><samp><span class="command">ar</span></samp> ignores an initial option spelt ‘<samp><span class="samp">-X32_64</span></samp>’, for
|
|
compatibility with AIX. The behaviour produced by this option is the
|
|
default for <span class="sc">gnu</span> <samp><span class="command">ar</span></samp>. <samp><span class="command">ar</span></samp> does not support any of the other
|
|
‘<samp><span class="samp">-X</span></samp>’ options; in particular, it does not support <samp><span class="option">-X32</span></samp>
|
|
which is the default for AIX <samp><span class="command">ar</span></samp>.
|
|
|
|
<p>The optional command line switch <samp><span class="option">--plugin</span></samp> <var>name</var> causes
|
|
<samp><span class="command">ar</span></samp> to load the plugin called <var>name</var> which adds support
|
|
for more file formats. This option is only available if the toolchain
|
|
has been built with plugin support enabled.
|
|
|
|
<p>The optional command line switch <samp><span class="option">--target</span></samp> <var>bfdname</var>
|
|
specifies that the archive members are in an object code format
|
|
different from your system's default format. See
|
|
See <a href="Target-Selection.html#Target-Selection">Target Selection</a>, for more information.
|
|
|
|
<!-- man end -->
|
|
</body></html>
|
|
|