| <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-2019 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, but if the modifier |
| ‘<samp><span class="samp">O</span></samp>’ 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 ‘<samp><span class="samp">v</span></samp>’ modifier should be included. |
| |
| <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. |
| </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">O</span></samp>’<dd><a name="index-offsets-of-files-28"></a>Display member offsets inside the archive. Use together with the ‘<samp><span class="samp">t</span></samp>’ |
| option. |
| |
| <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 compliant), 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-29"></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-30"></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-31"></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-32"></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-33"></a><a name="index-g_t_002d_002denable_002ddeterministic_002darchives-34"></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>The <samp><span class="command">ar</span></samp> program also supports some command-line options which |
| are neither modifiers nor actions, but which do change its behaviour |
| in specific ways: |
| |
| <dl> |
| <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. |
| |
| <br><dt>‘<samp><span class="samp">-X32_64</span></samp>’<dd><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>. |
| |
| <br><dt>‘<samp><span class="samp">--plugin </span><var>name</var></samp>’<dd><a name="index-plugins-35"></a>The optional command-line switch <samp><span class="option">--plugin </span><var>name</var></samp> causes |
| <samp><span class="command">ar</span></samp> to load the plugin called <var>name</var> 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 <samp><span class="option">--plugin</span></samp> is not provided, but plugin support has been |
| enabled then <samp><span class="command">ar</span></samp> iterates over the files in |
| <samp><span class="file">${libdir}/bfd-plugins</span></samp> in alphabetic order and the first |
| plugin that claims the object in question is used. |
| |
| <p>Please note that this plugin search directory is <em>not</em> the one |
| used by <samp><span class="command">ld</span></samp>'s <samp><span class="option">-plugin</span></samp> option. In order to make |
| <samp><span class="command">ar</span></samp> use the linker plugin it must be copied into the |
| <samp><span class="file">${libdir}/bfd-plugins</span></samp> directory. For GCC based compilations |
| the linker plugin is called <samp><span class="file">liblto_plugin.so.0.0.0</span></samp>. For Clang |
| based compilations it is called <samp><span class="file">LLVMgold.so</span></samp>. The GCC plugin |
| is always backwards compatible with earlier versions, so it is |
| sufficient to just copy the newest one. |
| |
| <br><dt>‘<samp><span class="samp">--target </span><var>target</var></samp>’<dd>The optional command-line switch <samp><span class="option">--target </span><var>bfdname</var></samp> |
| 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. |
| </dl> |
| <!-- man end --> |
| |
| </body></html> |
| |
