1AR(1)                        GNU Development Tools                       AR(1)
2
3
4

NAME

6       ar - create, modify, and extract from archives
7

SYNOPSIS

9       ar [-X32_64] [-]p[mod] [--plugin name] [--target bfdname] [--output
10       dirname] [--record-libdeps libdeps] [--thin] [relpos] [count] archive
11       [member...]
12

DESCRIPTION

14       The GNU ar program creates, modifies, and extracts from archives.  An
15       archive is a single file holding a collection of other files in a
16       structure that makes it possible to retrieve the original individual
17       files (called members of the archive).
18
19       The original files' contents, mode (permissions), timestamp, owner, and
20       group are preserved in the archive, and can be restored on extraction.
21
22       GNU ar can maintain archives whose members have names of any length;
23       however, depending on how ar is configured on your system, a limit on
24       member-name length may be imposed for compatibility with archive
25       formats maintained with other tools.  If it exists, the limit is often
26       15 characters (typical of formats related to a.out) or 16 characters
27       (typical of formats related to coff).
28
29       ar is considered a binary utility because archives of this sort are
30       most often used as libraries holding commonly needed subroutines.
31       Since libraries often will depend on other libraries, ar can also
32       record the dependencies of a library when the --record-libdeps option
33       is specified.
34
35       ar creates an index to the symbols defined in relocatable object
36       modules in the archive when you specify the modifier s.  Once created,
37       this index is updated in the archive whenever ar makes a change to its
38       contents (save for the q update operation).  An archive with such an
39       index speeds up linking to the library, and allows routines in the
40       library to call each other without regard to their placement in the
41       archive.
42
43       You may use nm -s or nm --print-armap to list this index table.  If an
44       archive lacks the table, another form of ar called ranlib can be used
45       to add just the table.
46
47       GNU ar can optionally create a thin archive, which contains a symbol
48       index and references to the original copies of the member files of the
49       archive.  This is useful for building libraries for use within a local
50       build tree, where the relocatable objects are expected to remain
51       available, and copying the contents of each object would only waste
52       time and space.
53
54       An archive can either be thin or it can be normal.  It cannot be both
55       at the same time.  Once an archive is created its format cannot be
56       changed without first deleting it and then creating a new archive in
57       its place.
58
59       Thin archives are also flattened, so that adding one thin archive to
60       another thin archive does not nest it, as would happen with a normal
61       archive.  Instead the elements of the first archive are added
62       individually to the second archive.
63
64       The paths to the elements of the archive are stored relative to the
65       archive itself.
66
67       GNU ar is designed to be compatible with two different facilities.  You
68       can control its activity using command-line options, like the different
69       varieties of ar on Unix systems; or, if you specify the single command-
70       line option -M, you can control it with a script supplied via standard
71       input, like the MRI "librarian" program.
72

OPTIONS

74       GNU ar allows you to mix the operation code p and modifier flags mod in
75       any order, within the first command-line argument.
76
77       If you wish, you may begin the first command-line argument with a dash.
78
79       The p keyletter specifies what operation to execute; it may be any of
80       the following, but you must specify only one of them:
81
82       d   Delete modules from the archive.  Specify the names of modules to
83           be deleted as member...; the archive is untouched if you specify no
84           files to delete.
85
86           If you specify the v modifier, ar lists each module as it is
87           deleted.
88
89       m   Use this operation to move members in an archive.
90
91           The ordering of members in an archive can make a difference in how
92           programs are linked using the library, if a symbol is defined in
93           more than one member.
94
95           If no modifiers are used with "m", any members you name in the
96           member arguments are moved to the end of the archive; you can use
97           the a, b, or i modifiers to move them to a specified place instead.
98
99       p   Print the specified members of the archive, to the standard output
100           file.  If the v modifier is specified, show the member name before
101           copying its contents to standard output.
102
103           If you specify no member arguments, all the files in the archive
104           are printed.
105
106       q   Quick append; Historically, add the files member... to the end of
107           archive, without checking for replacement.
108
109           The modifiers a, b, and i do not affect this operation; new members
110           are always placed at the end of the archive.
111
112           The modifier v makes ar list each file as it is appended.
113
114           Since the point of this operation is speed, implementations of ar
115           have the option of not updating the archive's symbol table if one
116           exists.  Too many different systems however assume that symbol
117           tables are always up-to-date, so GNU ar will rebuild the table even
118           with a quick append.
119
120           Note - GNU ar treats the command qs as a synonym for r - replacing
121           already existing files in the archive and appending new ones at the
122           end.
123
124       r   Insert the files member... into archive (with replacement). This
125           operation differs from q in that any previously existing members
126           are deleted if their names match those being added.
127
128           If one of the files named in member... does not exist, ar displays
129           an error message, and leaves undisturbed any existing members of
130           the archive matching that name.
131
132           By default, new members are added at the end of the file; but you
133           may use one of the modifiers a, b, or i to request placement
134           relative to some existing member.
135
136           The modifier v used with this operation elicits a line of output
137           for each file inserted, along with one of the letters a or r to
138           indicate whether the file was appended (no old member deleted) or
139           replaced.
140
141       s   Add an index to the archive, or update it if it already exists.
142           Note this command is an exception to the rule that there can only
143           be one command letter, as it is possible to use it as either a
144           command or a modifier.  In either case it does the same thing.
145
146       t   Display a table listing the contents of archive, or those of the
147           files listed in member... that are present in the archive.
148           Normally only the member name is shown, but if the modifier O is
149           specified, then the corresponding offset of the member is also
150           displayed.  Finally, in order to see the modes (permissions),
151           timestamp, owner, group, and size the v modifier should be
152           included.
153
154           If you do not specify a member, all files in the archive are
155           listed.
156
157           If there is more than one file with the same name (say, fie) in an
158           archive (say b.a), ar t b.a fie lists only the first instance; to
159           see them all, you must ask for a complete listing---in our example,
160           ar t b.a.
161
162       x   Extract members (named member) from the archive.  You can use the v
163           modifier with this operation, to request that ar list each name as
164           it extracts it.
165
166           If you do not specify a member, all files in the archive are
167           extracted.
168
169           Files cannot be extracted from a thin archive, and there are
170           restrictions on extracting from archives created with P: The paths
171           must not be absolute, may not contain "..", and any subdirectories
172           in the paths must exist.  If it is desired to avoid these
173           restrictions then used the --output option to specify an output
174           directory.
175
176       A number of modifiers (mod) may immediately follow the p keyletter, to
177       specify variations on an operation's behavior:
178
179       a   Add new files after an existing member of the archive.  If you use
180           the modifier a, the name of an existing archive member must be
181           present as the relpos argument, before the archive specification.
182
183       b   Add new files before an existing member of the archive.  If you use
184           the modifier b, the name of an existing archive member must be
185           present as the relpos argument, before the archive specification.
186           (same as i).
187
188       c   Create the archive.  The specified archive is always created if it
189           did not exist, when you request an update.  But a warning is issued
190           unless you specify in advance that you expect to create it, by
191           using this modifier.
192
193       D   Operate in deterministic mode.  When adding files and the archive
194           index use zero for UIDs, GIDs, timestamps, and use consistent file
195           modes for all files.  When this option is used, if ar is used with
196           identical options and identical input files, multiple runs will
197           create identical output files regardless of the input files'
198           owners, groups, file modes, or modification times.
199
200           If binutils was configured with --enable-deterministic-archives,
201           then this mode is on by default.  It can be disabled with the U
202           modifier, below.
203
204       f   Truncate names in the archive.  GNU ar will normally permit file
205           names of any length.  This will cause it to create archives which
206           are not compatible with the native ar program on some systems.  If
207           this is a concern, the f modifier may be used to truncate file
208           names when putting them in the archive.
209
210       i   Insert new files before an existing member of the archive.  If you
211           use the modifier i, the name of an existing archive member must be
212           present as the relpos argument, before the archive specification.
213           (same as b).
214
215       l   Specify dependencies of this library.  The dependencies must
216           immediately follow this option character, must use the same syntax
217           as the linker command line, and must be specified within a single
218           argument.  I.e., if multiple items are needed, they must be quoted
219           to form a single command line argument.  For example L
220           "-L/usr/local/lib -lmydep1 -lmydep2"
221
222       N   Uses the count parameter.  This is used if there are multiple
223           entries in the archive with the same name.  Extract or delete
224           instance count of the given name from the archive.
225
226       o   Preserve the original dates of members when extracting them.  If
227           you do not specify this modifier, files extracted from the archive
228           are stamped with the time of extraction.
229
230       O   Display member offsets inside the archive. Use together with the t
231           option.
232
233       P   Use the full path name when matching or storing names in the
234           archive.  Archives created with full path names are not POSIX
235           compliant, and thus may not work with tools other than up to date
236           GNU tools.  Modifying such archives with GNU ar without using P
237           will remove the full path names unless the archive is a thin
238           archive.  Note that P may be useful when adding files to a thin
239           archive since r without P ignores the path when choosing which
240           element to replace.  Thus
241
242                   ar rcST archive.a subdir/file1 subdir/file2 file1
243
244           will result in the first "subdir/file1" being replaced with "file1"
245           from the current directory.  Adding P will prevent this
246           replacement.
247
248       s   Write an object-file index into the archive, or update an existing
249           one, even if no other change is made to the archive.  You may use
250           this modifier flag either with any operation, or alone.  Running ar
251           s on an archive is equivalent to running ranlib on it.
252
253       S   Do not generate an archive symbol table.  This can speed up
254           building a large library in several steps.  The resulting archive
255           can not be used with the linker.  In order to build a symbol table,
256           you must omit the S modifier on the last execution of ar, or you
257           must run ranlib on the archive.
258
259       T   Deprecated alias for --thin.  T is not recommended because in many
260           ar implementations T has a different meaning, as specified by
261           X/Open System Interface.
262
263       u   Normally, ar r... inserts all files listed into the archive.  If
264           you would like to insert only those of the files you list that are
265           newer than existing members of the same names, use this modifier.
266           The u modifier is allowed only for the operation r (replace).  In
267           particular, the combination qu is not allowed, since checking the
268           timestamps would lose any speed advantage from the operation q.
269
270       U   Do not operate in deterministic mode.  This is the inverse of the D
271           modifier, above: added files and the archive index will get their
272           actual UID, GID, timestamp, and file mode values.
273
274           This is the default unless binutils was configured with
275           --enable-deterministic-archives.
276
277       v   This modifier requests the verbose version of an operation.  Many
278           operations display additional information, such as filenames
279           processed, when the modifier v is appended.
280
281       V   This modifier shows the version number of ar.
282
283       The ar program also supports some command-line options which are
284       neither modifiers nor actions, but which do change its behaviour in
285       specific ways:
286
287       --help
288           Displays the list of command-line options supported by ar and then
289           exits.
290
291       --version
292           Displays the version information of ar and then exits.
293
294       -X32_64
295           ar ignores an initial option spelled -X32_64, for compatibility
296           with AIX.  The behaviour produced by this option is the default for
297           GNU ar.  ar does not support any of the other -X options; in
298           particular, it does not support -X32 which is the default for AIX
299           ar.
300
301       --plugin name
302           The optional command-line switch --plugin name causes ar to load
303           the plugin called name which adds support for more file formats,
304           including object files with link-time optimization information.
305
306           This option is only available if the toolchain has been built with
307           plugin support enabled.
308
309           If --plugin is not provided, but plugin support has been enabled
310           then ar iterates over the files in ${libdir}/bfd-plugins in
311           alphabetic order and the first plugin that claims the object in
312           question is used.
313
314           Please note that this plugin search directory is not the one used
315           by ld's -plugin option.  In order to make ar use the  linker plugin
316           it must be copied into the ${libdir}/bfd-plugins directory.  For
317           GCC based compilations the linker plugin is called
318           liblto_plugin.so.0.0.0.  For Clang based compilations it is called
319           LLVMgold.so.  The GCC plugin is always backwards compatible with
320           earlier versions, so it is sufficient to just copy the newest one.
321
322       --target target
323           The optional command-line switch --target bfdname specifies that
324           the archive members are in an object code format different from
325           your system's default format.  See
326
327       --output dirname
328           The --output option can be used to specify a path to a directory
329           into which archive members should be extracted.  If this option is
330           not specified then the current directory will be used.
331
332           Note - although the presence of this option does imply a x
333           extraction operation that option must still be included on the
334           command line.
335
336       --record-libdeps libdeps
337           The --record-libdeps option is identical to the l modifier, just
338           handled in long form.
339
340       --thin
341           Make the specified archive a thin archive.  If it already exists
342           and is a regular archive, the existing members must be present in
343           the same directory as archive.
344
345       @file
346           Read command-line options from file.  The options read are inserted
347           in place of the original @file option.  If file does not exist, or
348           cannot be read, then the option will be treated literally, and not
349           removed.
350
351           Options in file are separated by whitespace.  A whitespace
352           character may be included in an option by surrounding the entire
353           option in either single or double quotes.  Any character (including
354           a backslash) may be included by prefixing the character to be
355           included with a backslash.  The file may itself contain additional
356           @file options; any such options will be processed recursively.
357

SEE ALSO

359       nm(1), ranlib(1), and the Info entries for binutils.
360
362       Copyright (c) 1991-2022 Free Software Foundation, Inc.
363
364       Permission is granted to copy, distribute and/or modify this document
365       under the terms of the GNU Free Documentation License, Version 1.3 or
366       any later version published by the Free Software Foundation; with no
367       Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
368       Texts.  A copy of the license is included in the section entitled "GNU
369       Free Documentation License".
370
371
372
373binutils-2.39                     2022-08-31                             AR(1)
Impressum