1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Copyright (C) 1991-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 7or any later version published by the Free Software Foundation; 8with no Invariant Sections, with no Front-Cover Texts, and with no 9Back-Cover Texts. A copy of the license is included in the 10section entitled "GNU Free Documentation License". 11 --> 12<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 13<head> 14<title>GNU Binary Utilities: ar cmdline</title> 15 16<meta name="description" content="GNU Binary Utilities: ar cmdline"> 17<meta name="keywords" content="GNU Binary Utilities: ar cmdline"> 18<meta name="resource-type" content="document"> 19<meta name="distribution" content="global"> 20<meta name="Generator" content="makeinfo"> 21<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 22<link href="index.html#Top" rel="start" title="Top"> 23<link href="Binutils-Index.html#Binutils-Index" rel="index" title="Binutils Index"> 24<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 25<link href="ar.html#ar" rel="up" title="ar"> 26<link href="ar-scripts.html#ar-scripts" rel="next" title="ar scripts"> 27<link href="ar.html#ar" rel="previous" title="ar"> 28<style type="text/css"> 29<!-- 30a.summary-letter {text-decoration: none} 31blockquote.smallquotation {font-size: smaller} 32div.display {margin-left: 3.2em} 33div.example {margin-left: 3.2em} 34div.indentedblock {margin-left: 3.2em} 35div.lisp {margin-left: 3.2em} 36div.smalldisplay {margin-left: 3.2em} 37div.smallexample {margin-left: 3.2em} 38div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 39div.smalllisp {margin-left: 3.2em} 40kbd {font-style:oblique} 41pre.display {font-family: inherit} 42pre.format {font-family: inherit} 43pre.menu-comment {font-family: serif} 44pre.menu-preformatted {font-family: serif} 45pre.smalldisplay {font-family: inherit; font-size: smaller} 46pre.smallexample {font-size: smaller} 47pre.smallformat {font-family: inherit; font-size: smaller} 48pre.smalllisp {font-size: smaller} 49span.nocodebreak {white-space:nowrap} 50span.nolinebreak {white-space:nowrap} 51span.roman {font-family:serif; font-weight:normal} 52span.sansserif {font-family:sans-serif; font-weight:normal} 53ul.no-bullet {list-style: none} 54--> 55</style> 56 57 58</head> 59 60<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 61<a name="ar-cmdline"></a> 62<div class="header"> 63<p> 64Next: <a href="ar-scripts.html#ar-scripts" accesskey="n" rel="next">ar scripts</a>, Up: <a href="ar.html#ar" accesskey="u" rel="up">ar</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Binutils-Index.html#Binutils-Index" title="Index" rel="index">Index</a>]</p> 65</div> 66<hr> 67<a name="Controlling-ar-on-the-Command-Line"></a> 68<h3 class="section">1.1 Controlling <code>ar</code> on the Command Line</h3> 69 70<div class="smallexample"> 71<pre class="smallexample">ar [<samp>-X32_64</samp>] [<samp>-</samp>]<var>p</var>[<var>mod</var>] [<samp>--plugin</samp> <var>name</var>] [<samp>--target</samp> <var>bfdname</var>] [<samp>--output</samp> <var>dirname</var>] [<samp>--record-libdeps</samp> <var>libdeps</var>] [<var>relpos</var>] [<var>count</var>] <var>archive</var> [<var>member</var>…] 72</pre></div> 73 74<a name="index-Unix-compatibility_002c-ar"></a> 75<p>When you use <code>ar</code> in the Unix style, <code>ar</code> insists on at least two 76arguments to execute: one keyletter specifying the <em>operation</em> 77(optionally accompanied by other keyletters specifying 78<em>modifiers</em>), and the archive name to act on. 79</p> 80<p>Most operations can also accept further <var>member</var> arguments, 81specifying particular files to operate on. 82</p> 83 84<p><small>GNU</small> <code>ar</code> allows you to mix the operation code <var>p</var> and modifier 85flags <var>mod</var> in any order, within the first command-line argument. 86</p> 87<p>If you wish, you may begin the first command-line argument with a 88dash. 89</p> 90<a name="index-operations-on-archive"></a> 91<p>The <var>p</var> keyletter specifies what operation to execute; it may be 92any of the following, but you must specify only one of them: 93</p> 94<dl compact="compact"> 95<dt>‘<samp>d</samp>’</dt> 96<dd><a name="index-deleting-from-archive"></a> 97<p><em>Delete</em> modules from the archive. Specify the names of modules to 98be deleted as <var>member</var>…; the archive is untouched if you 99specify no files to delete. 100</p> 101<p>If you specify the ‘<samp>v</samp>’ modifier, <code>ar</code> lists each module 102as it is deleted. 103</p> 104</dd> 105<dt>‘<samp>m</samp>’</dt> 106<dd><a name="index-moving-in-archive"></a> 107<p>Use this operation to <em>move</em> members in an archive. 108</p> 109<p>The ordering of members in an archive can make a difference in how 110programs are linked using the library, if a symbol is defined in more 111than one member. 112</p> 113<p>If no modifiers are used with <code>m</code>, any members you name in the 114<var>member</var> arguments are moved to the <em>end</em> of the archive; 115you can use the ‘<samp>a</samp>’, ‘<samp>b</samp>’, or ‘<samp>i</samp>’ modifiers to move them to a 116specified place instead. 117</p> 118</dd> 119<dt>‘<samp>p</samp>’</dt> 120<dd><a name="index-printing-from-archive"></a> 121<p><em>Print</em> the specified members of the archive, to the standard 122output file. If the ‘<samp>v</samp>’ modifier is specified, show the member 123name before copying its contents to standard output. 124</p> 125<p>If you specify no <var>member</var> arguments, all the files in the archive are 126printed. 127</p> 128</dd> 129<dt>‘<samp>q</samp>’</dt> 130<dd><a name="index-quick-append-to-archive"></a> 131<p><em>Quick append</em>; Historically, add the files <var>member</var>… to the end of 132<var>archive</var>, without checking for replacement. 133</p> 134<p>The modifiers ‘<samp>a</samp>’, ‘<samp>b</samp>’, and ‘<samp>i</samp>’ do <em>not</em> affect this 135operation; new members are always placed at the end of the archive. 136</p> 137<p>The modifier ‘<samp>v</samp>’ makes <code>ar</code> list each file as it is appended. 138</p> 139<p>Since the point of this operation is speed, implementations of 140<code>ar</code> have the option of not updating the archive’s symbol 141table if one exists. Too many different systems however assume that 142symbol tables are always up-to-date, so <small>GNU</small> <code>ar</code> will 143rebuild the table even with a quick append. 144</p> 145<p>Note - <small>GNU</small> <code>ar</code> treats the command ‘<samp>qs</samp>’ as a 146synonym for ‘<samp>r</samp>’ - replacing already existing files in the 147archive and appending new ones at the end. 148</p> 149</dd> 150<dt>‘<samp>r</samp>’</dt> 151<dd><a name="index-replacement-in-archive"></a> 152<p>Insert the files <var>member</var>… into <var>archive</var> (with 153<em>replacement</em>). This operation differs from ‘<samp>q</samp>’ in that any 154previously existing members are deleted if their names match those being 155added. 156</p> 157<p>If one of the files named in <var>member</var>… does not exist, <code>ar</code> 158displays an error message, and leaves undisturbed any existing members 159of the archive matching that name. 160</p> 161<p>By default, new members are added at the end of the file; but you may 162use one of the modifiers ‘<samp>a</samp>’, ‘<samp>b</samp>’, or ‘<samp>i</samp>’ to request 163placement relative to some existing member. 164</p> 165<p>The modifier ‘<samp>v</samp>’ used with this operation elicits a line of 166output for each file inserted, along with one of the letters ‘<samp>a</samp>’ or 167‘<samp>r</samp>’ to indicate whether the file was appended (no old member 168deleted) or replaced. 169</p> 170</dd> 171<dt>‘<samp>s</samp>’</dt> 172<dd><a name="index-ranlib"></a> 173<p>Add an index to the archive, or update it if it already exists. Note 174this command is an exception to the rule that there can only be one 175command letter, as it is possible to use it as either a command or a 176modifier. In either case it does the same thing. 177</p> 178</dd> 179<dt>‘<samp>t</samp>’</dt> 180<dd><a name="index-contents-of-archive"></a> 181<p>Display a <em>table</em> listing the contents of <var>archive</var>, or those 182of the files listed in <var>member</var>… that are present in the 183archive. Normally only the member name is shown, but if the modifier 184‘<samp>O</samp>’ is specified, then the corresponding offset of the member is also 185displayed. Finally, in order to see the modes (permissions), timestamp, 186owner, group, and size the ‘<samp>v</samp>’ modifier should be included. 187</p> 188<p>If you do not specify a <var>member</var>, all files in the archive 189are listed. 190</p> 191<a name="index-repeated-names-in-archive"></a> 192<a name="index-name-duplication-in-archive"></a> 193<p>If there is more than one file with the same name (say, ‘<samp>fie</samp>’) in 194an archive (say ‘<samp>b.a</samp>’), ‘<samp>ar t b.a fie</samp>’ lists only the 195first instance; to see them all, you must ask for a complete 196listing—in our example, ‘<samp>ar t b.a</samp>’. 197</p> 198</dd> 199<dt>‘<samp>x</samp>’</dt> 200<dd><a name="index-extract-from-archive"></a> 201<p><em>Extract</em> members (named <var>member</var>) from the archive. You can 202use the ‘<samp>v</samp>’ modifier with this operation, to request that 203<code>ar</code> list each name as it extracts it. 204</p> 205<p>If you do not specify a <var>member</var>, all files in the archive 206are extracted. 207</p> 208<p>Files cannot be extracted from a thin archive, and there are 209restrictions on extracting from archives created with <samp>P</samp>: The 210paths must not be absolute, may not contain <code>..</code>, and any 211subdirectories in the paths must exist. If it is desired to avoid 212these restrictions then used the <samp>--output</samp> option to specify 213an output directory. 214</p></dd> 215</dl> 216 217<p>A number of modifiers (<var>mod</var>) may immediately follow the <var>p</var> 218keyletter, to specify variations on an operation’s behavior: 219</p> 220<dl compact="compact"> 221<dt>‘<samp>a</samp>’</dt> 222<dd><a name="index-relative-placement-in-archive"></a> 223<p>Add new files <em>after</em> an existing member of the 224archive. If you use the modifier ‘<samp>a</samp>’, the name of an existing archive 225member must be present as the <var>relpos</var> argument, before the 226<var>archive</var> specification. 227</p> 228</dd> 229<dt>‘<samp>b</samp>’</dt> 230<dd><p>Add new files <em>before</em> an existing member of the 231archive. If you use the modifier ‘<samp>b</samp>’, the name of an existing archive 232member must be present as the <var>relpos</var> argument, before the 233<var>archive</var> specification. (same as ‘<samp>i</samp>’). 234</p> 235</dd> 236<dt>‘<samp>c</samp>’</dt> 237<dd><a name="index-creating-archives"></a> 238<p><em>Create</em> the archive. The specified <var>archive</var> is always 239created if it did not exist, when you request an update. But a warning is 240issued unless you specify in advance that you expect to create it, by 241using this modifier. 242</p> 243</dd> 244<dt>‘<samp>D</samp>’</dt> 245<dd><a name="index-deterministic-archives"></a> 246<a name="index-_002d_002denable_002ddeterministic_002darchives"></a> 247<p>Operate in <em>deterministic</em> mode. When adding files and the archive 248index use zero for UIDs, GIDs, timestamps, and use consistent file modes 249for all files. When this option is used, if <code>ar</code> is used with 250identical options and identical input files, multiple runs will create 251identical output files regardless of the input files’ owners, groups, 252file modes, or modification times. 253</p> 254<p>If <samp>binutils</samp> was configured with 255<samp>--enable-deterministic-archives</samp>, then this mode is on by default. 256It can be disabled with the ‘<samp>U</samp>’ modifier, below. 257</p> 258</dd> 259<dt>‘<samp>f</samp>’</dt> 260<dd><p>Truncate names in the archive. <small>GNU</small> <code>ar</code> will normally permit file 261names of any length. This will cause it to create archives which are 262not compatible with the native <code>ar</code> program on some systems. If 263this is a concern, the ‘<samp>f</samp>’ modifier may be used to truncate file 264names when putting them in the archive. 265</p> 266</dd> 267<dt>‘<samp>i</samp>’</dt> 268<dd><p>Insert new files <em>before</em> an existing member of the 269archive. If you use the modifier ‘<samp>i</samp>’, the name of an existing archive 270member must be present as the <var>relpos</var> argument, before the 271<var>archive</var> specification. (same as ‘<samp>b</samp>’). 272</p> 273</dd> 274<dt>‘<samp>l</samp>’</dt> 275<dd><p>Specify dependencies of this library. The dependencies must immediately 276follow this option character, must use the same syntax as the linker 277command line, and must be specified within a single argument. I.e., if 278multiple items are needed, they must be quoted to form a single command 279line argument. For example ‘<samp>L "-L/usr/local/lib -lmydep1 -lmydep2"</samp>’ 280</p> 281</dd> 282<dt>‘<samp>N</samp>’</dt> 283<dd><p>Uses the <var>count</var> parameter. This is used if there are multiple 284entries in the archive with the same name. Extract or delete instance 285<var>count</var> of the given name from the archive. 286</p> 287</dd> 288<dt>‘<samp>o</samp>’</dt> 289<dd><a name="index-dates-in-archive"></a> 290<p>Preserve the <em>original</em> dates of members when extracting them. If 291you do not specify this modifier, files extracted from the archive 292are stamped with the time of extraction. 293</p> 294</dd> 295<dt>‘<samp>O</samp>’</dt> 296<dd><a name="index-offsets-of-files"></a> 297<p>Display member offsets inside the archive. Use together with the ‘<samp>t</samp>’ 298option. 299</p> 300</dd> 301<dt>‘<samp>P</samp>’</dt> 302<dd><p>Use the full path name when matching or storing names in the archive. 303Archives created with full path names are not POSIX compliant, and 304thus may not work with tools other than up to date <small>GNU</small> tools. 305Modifying such archives with <small>GNU</small> <code>ar</code> without using 306<samp>P</samp> will remove the full path names unless the archive is a 307thin archive. Note that <samp>P</samp> may be useful when adding files to 308a thin archive since <samp>r</samp> without <samp>P</samp> ignores the path 309when choosing which element to replace. Thus 310</p><div class="smallexample"> 311<pre class="smallexample">ar rcST archive.a subdir/file1 subdir/file2 file1 312</pre></div> 313<p>will result in the first <code>subdir/file1</code> being replaced with 314<code>file1</code> from the current directory. Adding <samp>P</samp> will 315prevent this replacement. 316</p> 317</dd> 318<dt>‘<samp>s</samp>’</dt> 319<dd><a name="index-writing-archive-index"></a> 320<p>Write an object-file index into the archive, or update an existing one, 321even if no other change is made to the archive. You may use this modifier 322flag either with any operation, or alone. Running ‘<samp>ar s</samp>’ on an 323archive is equivalent to running ‘<samp>ranlib</samp>’ on it. 324</p> 325</dd> 326<dt>‘<samp>S</samp>’</dt> 327<dd><a name="index-not-writing-archive-index"></a> 328<p>Do not generate an archive symbol table. This can speed up building a 329large library in several steps. The resulting archive can not be used 330with the linker. In order to build a symbol table, you must omit the 331‘<samp>S</samp>’ modifier on the last execution of ‘<samp>ar</samp>’, or you must run 332‘<samp>ranlib</samp>’ on the archive. 333</p> 334</dd> 335<dt>‘<samp>T</samp>’</dt> 336<dd><a name="index-creating-thin-archive"></a> 337<p>Make the specified <var>archive</var> a <em>thin</em> archive. If it already 338exists and is a regular archive, the existing members must be present 339in the same directory as <var>archive</var>. 340</p> 341</dd> 342<dt>‘<samp>u</samp>’</dt> 343<dd><a name="index-updating-an-archive"></a> 344<p>Normally, ‘<samp>ar r</samp>’… inserts all files 345listed into the archive. If you would like to insert <em>only</em> those 346of the files you list that are newer than existing members of the same 347names, use this modifier. The ‘<samp>u</samp>’ modifier is allowed only for the 348operation ‘<samp>r</samp>’ (replace). In particular, the combination ‘<samp>qu</samp>’ is 349not allowed, since checking the timestamps would lose any speed 350advantage from the operation ‘<samp>q</samp>’. 351</p> 352</dd> 353<dt>‘<samp>U</samp>’</dt> 354<dd><a name="index-deterministic-archives-1"></a> 355<a name="index-_002d_002denable_002ddeterministic_002darchives-1"></a> 356<p>Do <em>not</em> operate in <em>deterministic</em> mode. This is the inverse 357of the ‘<samp>D</samp>’ modifier, above: added files and the archive index will 358get their actual UID, GID, timestamp, and file mode values. 359</p> 360<p>This is the default unless <samp>binutils</samp> was configured with 361<samp>--enable-deterministic-archives</samp>. 362</p> 363</dd> 364<dt>‘<samp>v</samp>’</dt> 365<dd><p>This modifier requests the <em>verbose</em> version of an operation. Many 366operations display additional information, such as filenames processed, 367when the modifier ‘<samp>v</samp>’ is appended. 368</p> 369</dd> 370<dt>‘<samp>V</samp>’</dt> 371<dd><p>This modifier shows the version number of <code>ar</code>. 372</p></dd> 373</dl> 374 375<p>The <code>ar</code> program also supports some command-line options which 376are neither modifiers nor actions, but which do change its behaviour 377in specific ways: 378</p> 379<dl compact="compact"> 380<dt>‘<samp>--help</samp>’</dt> 381<dd><p>Displays the list of command-line options supported by <code>ar</code> 382and then exits. 383</p> 384</dd> 385<dt>‘<samp>--version</samp>’</dt> 386<dd><p>Displays the version information of <code>ar</code> and then exits. 387</p> 388</dd> 389<dt>‘<samp>-X32_64</samp>’</dt> 390<dd><p><code>ar</code> ignores an initial option spelled ‘<samp>-X32_64</samp>’, for 391compatibility with AIX. The behaviour produced by this option is the 392default for <small>GNU</small> <code>ar</code>. <code>ar</code> does not support any 393of the other ‘<samp>-X</samp>’ options; in particular, it does not support 394<samp>-X32</samp> which is the default for AIX <code>ar</code>. 395</p> 396</dd> 397<dt>‘<samp>--plugin <var>name</var></samp>’</dt> 398<dd><a name="index-plugins"></a> 399<p>The optional command-line switch <samp>--plugin <var>name</var></samp> causes 400<code>ar</code> to load the plugin called <var>name</var> which adds support 401for more file formats, including object files with link-time 402optimization information. 403</p> 404<p>This option is only available if the toolchain has been built with 405plugin support enabled. 406</p> 407<p>If <samp>--plugin</samp> is not provided, but plugin support has been 408enabled then <code>ar</code> iterates over the files in 409<samp>${libdir}/bfd-plugins</samp> in alphabetic order and the first 410plugin that claims the object in question is used. 411</p> 412<p>Please note that this plugin search directory is <em>not</em> the one 413used by <code>ld</code>’s <samp>-plugin</samp> option. In order to make 414<code>ar</code> use the linker plugin it must be copied into the 415<samp>${libdir}/bfd-plugins</samp> directory. For GCC based compilations 416the linker plugin is called <samp>liblto_plugin.so.0.0.0</samp>. For Clang 417based compilations it is called <samp>LLVMgold.so</samp>. The GCC plugin 418is always backwards compatible with earlier versions, so it is 419sufficient to just copy the newest one. 420</p> 421</dd> 422<dt>‘<samp>--target <var>target</var></samp>’</dt> 423<dd><p>The optional command-line switch <samp>--target <var>bfdname</var></samp> 424specifies that the archive members are in an object code format 425different from your system’s default format. See 426See <a href="Target-Selection.html#Target-Selection">Target Selection</a>, for more information. 427</p> 428</dd> 429<dt>‘<samp>--output <var>dirname</var></samp>’</dt> 430<dd><p>The <samp>--output</samp> option can be used to specify a path to a 431directory into which archive members should be extracted. If this 432option is not specified then the current directory will be used. 433</p> 434<p>Note - although the presence of this option does imply a <samp>x</samp> 435extraction operation that option must still be included on the command 436line. 437</p> 438</dd> 439<dt>‘<samp>--record-libdeps <var>libdeps</var></samp>’</dt> 440<dd><p>The <samp>--record-libdeps</samp> option is identical to the <samp>l</samp> modifier, 441just handled in long form. 442</p> 443</dd> 444</dl> 445 446 447<hr> 448<div class="header"> 449<p> 450Next: <a href="ar-scripts.html#ar-scripts" accesskey="n" rel="next">ar scripts</a>, Up: <a href="ar.html#ar" accesskey="u" rel="up">ar</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Binutils-Index.html#Binutils-Index" title="Index" rel="index">Index</a>]</p> 451</div> 452 453 454 455</body> 456</html> 457