Debian Codegraph @

upstream/debian-unstable/man1/ar.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "AR 1"
58 .TH AR 1 2026-03-05 binutils-2.46 "GNU Development Tools"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 ar \- create, modify, and extract from archives
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 ar [\fB\-X32_64\fR] [\fB\-\fR]\fIp\fR[\fImod\fR] [\fB\-\-plugin\fR \fIname\fR] [\fB\-\-target\fR \fIbfdname\fR] [\fB\-\-output\fR \fIdirname\fR] [\fB\-\-record\-libdeps\fR \fIlibdeps\fR] [\fB\-\-thin\fR] [\fIrelpos\fR] [\fIcount\fR] \fIarchive\fR [\fImember\fR...]
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 The GNU \fBar\fR program creates, modifies, and extracts from
71 archives. An \fIarchive\fR is a single file holding a collection of
72 other files in a structure that makes it possible to retrieve
73 the original individual files (called \fImembers\fR of the archive).
74 .PP
75 The original files' contents, mode (permissions), timestamp, owner, and
76 group are preserved in the archive, and can be restored on
77 extraction.
78 .PP
79 GNU \fBar\fR can maintain archives whose members have names of any
80 length; however, depending on how \fBar\fR is configured on your
81 system, a limit on member-name length may be imposed for compatibility
82 with archive formats maintained with other tools. If it exists, the
83 limit is often 15 characters (typical of formats related to a.out) or 16
84 characters (typical of formats related to coff).
85 .PP
86 \&\fBar\fR is considered a binary utility because archives of this sort
87 are most often used as \fIlibraries\fR holding commonly needed
88 subroutines. Since libraries often will depend on other libraries,
89 \&\fBar\fR can also record the dependencies of a library when the
90 \&\fB\-\-record\-libdeps\fR option is specified.
91 .PP
92 \&\fBar\fR creates an index to the symbols defined in relocatable
93 object modules in the archive when you specify the modifier \fBs\fR.
94 Once created, this index is updated in the archive whenever \fBar\fR
95 makes a change to its contents (save for the \fBq\fR update operation).
96 An archive with such an index speeds up linking to the library, and
97 allows routines in the library to call each other without regard to
98 their placement in the archive.
99 .PP
100 You may use \fBnm \-s\fR or \fBnm \-\-print\-armap\fR to list this index
101 table. If an archive lacks the table, another form of \fBar\fR called
102 \&\fBranlib\fR can be used to add just the table.
103 .PP
104 GNU \fBar\fR can optionally create a \fIthin\fR archive,
105 which contains a symbol index and references to the original copies
106 of the member files of the archive. This is useful for building
107 libraries for use within a local build tree, where the relocatable
108 objects are expected to remain available, and copying the contents of
109 each object would only waste time and space.
110 .PP
111 An archive can either be \fIthin\fR or it can be normal. It cannot
112 be both at the same time. Once an archive is created its format
113 cannot be changed without first deleting it and then creating a new
114 archive in its place.
115 .PP
116 Thin archives are also \fIflattened\fR, so that adding one thin
117 archive to another thin archive does not nest it, as would happen with
118 a normal archive. Instead the elements of the first archive are added
119 individually to the second archive.
120 .PP
121 The paths to the elements of the archive are stored relative to the
122 archive itself.
123 .PP
124 GNU \fBar\fR is designed to be compatible with two different
125 facilities. You can control its activity using command-line options,
126 like the different varieties of \fBar\fR on Unix systems; or, if you
127 specify the single command-line option \fB\-M\fR, you can control it
128 with a script supplied via standard input, like the MRI "librarian"
129 program.
130 .SH OPTIONS
131 .IX Header "OPTIONS"
132 GNU \fBar\fR allows you to mix the operation code \fIp\fR and modifier
133 flags \fImod\fR in any order, within the first command-line argument.
134 .PP
135 If you wish, you may begin the first command-line argument with a
136 dash.
137 .PP
138 The \fIp\fR keyletter specifies what operation to execute; it may be
139 any of the following, but you must specify only one of them:
140 .IP \fBd\fR 4
141 .IX Item "d"
142 \&\fIDelete\fR modules from the archive. Specify the names of modules to
143 be deleted as \fImember\fR...; the archive is untouched if you
144 specify no files to delete.
145 .Sp
146 If you specify the \fBv\fR modifier, \fBar\fR lists each module
147 as it is deleted.
148 .IP \fBm\fR 4
149 .IX Item "m"
150 Use this operation to \fImove\fR members in an archive.
151 .Sp
152 The ordering of members in an archive can make a difference in how
153 programs are linked using the library, if a symbol is defined in more
154 than one member.
155 .Sp
156 If no modifiers are used with \f(CW\*(C`m\*(C'\fR, any members you name in the
157 \&\fImember\fR arguments are moved to the \fIend\fR of the archive;
158 you can use the \fBa\fR, \fBb\fR, or \fBi\fR modifiers to move them to a
159 specified place instead.
160 .IP \fBp\fR 4
161 .IX Item "p"
162 \&\fIPrint\fR the specified members of the archive, to the standard
163 output file. If the \fBv\fR modifier is specified, show the member
164 name before copying its contents to standard output.
165 .Sp
166 If you specify no \fImember\fR arguments, all the files in the archive are
167 printed.
168 .IP \fBq\fR 4
169 .IX Item "q"
170 \&\fIQuick append\fR; Historically, add the files \fImember\fR... to the end of
171 \&\fIarchive\fR, without checking for replacement.
172 .Sp
173 The modifiers \fBa\fR, \fBb\fR, and \fBi\fR do \fInot\fR affect this
174 operation; new members are always placed at the end of the archive.
175 .Sp
176 The modifier \fBv\fR makes \fBar\fR list each file as it is appended.
177 .Sp
178 Since the point of this operation is speed, implementations of
179 \&\fBar\fR have the option of not updating the archive's symbol
180 table if one exists. Too many different systems however assume that
181 symbol tables are always up-to-date, so GNU \fBar\fR will
182 rebuild the table even with a quick append.
183 .Sp
184 Note \- GNU \fBar\fR treats the command \fBqs\fR as a
185 synonym for \fBr\fR \- replacing already existing files in the
186 archive and appending new ones at the end.
187 .IP \fBr\fR 4
188 .IX Item "r"
189 Insert the files \fImember\fR... into \fIarchive\fR (with
190 \&\fIreplacement\fR). This operation differs from \fBq\fR in that any
191 previously existing members are deleted if their names match those being
192 added.
193 .Sp
194 If one of the files named in \fImember\fR... does not exist, \fBar\fR
195 displays an error message, and leaves undisturbed any existing members
196 of the archive matching that name.
197 .Sp
198 By default, new members are added at the end of the file; but you may
199 use one of the modifiers \fBa\fR, \fBb\fR, or \fBi\fR to request
200 placement relative to some existing member.
201 .Sp
202 The modifier \fBv\fR used with this operation elicits a line of
203 output for each file inserted, along with one of the letters \fBa\fR or
204 \&\fBr\fR to indicate whether the file was appended (no old member
205 deleted) or replaced.
206 .IP \fBs\fR 4
207 .IX Item "s"
208 Add an index to the archive, or update it if it already exists. Note
209 this command is an exception to the rule that there can only be one
210 command letter, as it is possible to use it as either a command or a
211 modifier. In either case it does the same thing.
212 .IP \fBt\fR 4
213 .IX Item "t"
214 Display a \fItable\fR listing the contents of \fIarchive\fR, or those
215 of the files listed in \fImember\fR... that are present in the
216 archive. Normally only the member name is shown, but if the modifier
217 \&\fBO\fR is specified, then the corresponding offset of the member is also
218 displayed. Finally, in order to see the modes (permissions), timestamp,
219 owner, group, and size the \fBv\fR modifier should be included.
220 .Sp
221 If you do not specify a \fImember\fR, all files in the archive
222 are listed.
223 .Sp
224 If there is more than one file with the same name (say, \fBfie\fR) in
225 an archive (say \fBb.a\fR), \fBar t b.a fie\fR lists only the
226 first instance; to see them all, you must ask for a complete
227 listing\-\-\-in our example, \fBar t b.a\fR.
228 .IP \fBx\fR 4
229 .IX Item "x"
230 \&\fIExtract\fR members (named \fImember\fR) from the archive. You can
231 use the \fBv\fR modifier with this operation, to request that
232 \&\fBar\fR list each name as it extracts it.
233 .Sp
234 If you do not specify a \fImember\fR, all files in the archive
235 are extracted.
236 .Sp
237 Files cannot be extracted from a thin archive, and there are
238 restrictions on extracting from archives created with \fBP\fR: The
239 paths must not be absolute, may not contain \f(CW\*(C`..\*(C'\fR, and any
240 subdirectories in the paths must exist. If it is desired to avoid
241 these restrictions then used the \fB\-\-output\fR option to specify
242 an output directory.
243 .PP
244 A number of modifiers (\fImod\fR) may immediately follow the \fIp\fR
245 keyletter, to specify variations on an operation's behavior:
246 .IP \fBa\fR 4
247 .IX Item "a"
248 Add new files \fIafter\fR an existing member of the
249 archive. If you use the modifier \fBa\fR, the name of an existing archive
250 member must be present as the \fIrelpos\fR argument, before the
251 \&\fIarchive\fR specification.
252 .IP \fBb\fR 4
253 .IX Item "b"
254 Add new files \fIbefore\fR an existing member of the
255 archive. If you use the modifier \fBb\fR, the name of an existing archive
256 member must be present as the \fIrelpos\fR argument, before the
257 \&\fIarchive\fR specification. (same as \fBi\fR).
258 .IP \fBc\fR 4
259 .IX Item "c"
260 \&\fICreate\fR the archive. The specified \fIarchive\fR is always
261 created if it did not exist, when you request an update. But a warning is
262 issued unless you specify in advance that you expect to create it, by
263 using this modifier.
264 .IP \fBD\fR 4
265 .IX Item "D"
266 Operate in \fIdeterministic\fR mode. When adding files and the archive
267 index use zero for UIDs, GIDs, timestamps, and use consistent file modes
268 for all files. When this option is used, if \fBar\fR is used with
269 identical options and identical input files, multiple runs will create
270 identical output files regardless of the input files' owners, groups,
271 file modes, or modification times.
272 .Sp
273 If \fIbinutils\fR was configured with
274 \&\fB\-\-enable\-deterministic\-archives\fR, then this mode is on by default.
275 It can be disabled with the \fBU\fR modifier, below.
276 .IP \fBf\fR 4
277 .IX Item "f"
278 Truncate names in the archive. GNU \fBar\fR will normally permit file
279 names of any length. This will cause it to create archives which are
280 not compatible with the native \fBar\fR program on some systems. If
281 this is a concern, the \fBf\fR modifier may be used to truncate file
282 names when putting them in the archive.
283 .IP \fBi\fR 4
284 .IX Item "i"
285 Insert new files \fIbefore\fR an existing member of the
286 archive. If you use the modifier \fBi\fR, the name of an existing archive
287 member must be present as the \fIrelpos\fR argument, before the
288 \&\fIarchive\fR specification. (same as \fBb\fR).
289 .IP \fBl\fR 4
290 .IX Item "l"
291 Specify dependencies of this library. The dependencies must immediately
292 follow this option character, must use the same syntax as the linker
293 command line, and must be specified within a single argument. I.e., if
294 multiple items are needed, they must be quoted to form a single command
295 line argument. For example \fBl "\-L/usr/local/lib \-lmydep1 \-lmydep2"\fR
296 .IP \fBN\fR 4
297 .IX Item "N"
298 Uses the \fIcount\fR parameter. This is used if there are multiple
299 entries in the archive with the same name. Extract or delete instance
300 \&\fIcount\fR of the given name from the archive.
301 .IP \fBo\fR 4
302 .IX Item "o"
303 Preserve the \fIoriginal\fR dates of members when extracting them. If
304 you do not specify this modifier, files extracted from the archive
305 are stamped with the time of extraction.
306 .IP \fBO\fR 4
307 .IX Item "O"
308 Display member offsets inside the archive. Use together with the \fBt\fR
309 option.
310 .IP \fBP\fR 4
311 .IX Item "P"
312 Use the full path name when matching or storing names in the archive.
313 Archives created with full path names are not POSIX compliant, and
314 thus may not work with tools other than up to date GNU tools.
315 Modifying such archives with GNU \fBar\fR without using
316 \&\fBP\fR will remove the full path names unless the archive is a
317 thin archive. Note that \fBP\fR may be useful when adding files to
318 a thin archive since \fBr\fR without \fBP\fR ignores the path
319 when choosing which element to replace. Thus
320 .Sp
321 .Vb 1
322 \& ar rcST archive.a subdir/file1 subdir/file2 file1
323 .Ve
324 .Sp
325 will result in the first \f(CW\*(C`subdir/file1\*(C'\fR being replaced with
326 \&\f(CW\*(C`file1\*(C'\fR from the current directory. Adding \fBP\fR will
327 prevent this replacement.
328 .IP \fBs\fR 4
329 .IX Item "s"
330 Write an object-file index into the archive, or update an existing one,
331 even if no other change is made to the archive. You may use this modifier
332 flag either with any operation, or alone. Running \fBar s\fR on an
333 archive is equivalent to running \fBranlib\fR on it.
334 .IP \fBS\fR 4
335 .IX Item "S"
336 Do not generate an archive symbol table. This can speed up building a
337 large library in several steps. The resulting archive can not be used
338 with the linker. In order to build a symbol table, you must omit the
339 \&\fBS\fR modifier on the last execution of \fBar\fR, or you must run
340 \&\fBranlib\fR on the archive.
341 .IP \fBT\fR 4
342 .IX Item "T"
343 Deprecated alias for \fB\-\-thin\fR. \fBT\fR is not recommended because in
344 many ar implementations \fBT\fR has a different meaning, as specified by
345 X/Open System Interface.
346 .IP \fBu\fR 4
347 .IX Item "u"
348 Normally, \fBar r\fR... inserts all files
349 listed into the archive. If you would like to insert \fIonly\fR those
350 of the files you list that are newer than existing members of the same
351 names, use this modifier. The \fBu\fR modifier is allowed only for the
352 operation \fBr\fR (replace). In particular, the combination \fBqu\fR is
353 not allowed, since checking the timestamps would lose any speed
354 advantage from the operation \fBq\fR.
355 .Sp
356 Note \- if an archive has been created in a deterministic manner, eg
357 via the use of the \fBD\fR modifier, then replacement will always
358 happen and the \fBu\fR modifier will be ineffective.
359 .IP \fBU\fR 4
360 .IX Item "U"
361 Do \fInot\fR operate in \fIdeterministic\fR mode. This is the inverse
362 of the \fBD\fR modifier, above: added files and the archive index will
363 get their actual UID, GID, timestamp, and file mode values.
364 .Sp
365 This is the default unless \fIbinutils\fR was configured with
366 \&\fB\-\-enable\-deterministic\-archives\fR.
367 .IP \fBv\fR 4
368 .IX Item "v"
369 This modifier requests the \fIverbose\fR version of an operation. Many
370 operations display additional information, such as filenames processed,
371 when the modifier \fBv\fR is appended.
372 .IP \fBV\fR 4
373 .IX Item "V"
374 This modifier shows the version number of \fBar\fR.
375 .PP
376 The \fBar\fR program also supports some command-line options which
377 are neither modifiers nor actions, but which do change its behaviour
378 in specific ways:
379 .IP \fB\-\-help\fR 4
380 .IX Item "--help"
381 Displays the list of command-line options supported by \fBar\fR
382 and then exits.
383 .IP \fB\-\-version\fR 4
384 .IX Item "--version"
385 Displays the version information of \fBar\fR and then exits.
386 .IP \fB\-X32_64\fR 4
387 .IX Item "-X32_64"
388 \&\fBar\fR ignores an initial option spelled \fB\-X32_64\fR, for
389 compatibility with AIX. The behaviour produced by this option is the
390 default for GNU \fBar\fR. \fBar\fR does not support any
391 of the other \fB\-X\fR options; in particular, it does not support
392 \&\fB\-X32\fR which is the default for AIX \fBar\fR.
393 .IP "\fB\-\-plugin\fR \fIname\fR" 4
394 .IX Item "--plugin name"
395 The optional command-line switch \fB\-\-plugin\fR \fIname\fR causes
396 \&\fBar\fR to load the plugin called \fIname\fR which adds support
397 for more file formats, including object files with link-time
398 optimization information.
399 .Sp
400 This option is only available if the toolchain has been built with
401 plugin support enabled.
402 .Sp
403 If \fB\-\-plugin\fR is not provided, but plugin support has been
404 enabled then \fBar\fR iterates over the files in
405 \&\fI${libdir}/bfd\-plugins\fR in alphabetic order and the first
406 plugin that claims the object in question is used.
407 .Sp
408 Please note that this plugin search directory is \fInot\fR the one
409 used by \fBld\fR's \fB\-plugin\fR option. In order to make
410 \&\fBar\fR use the linker plugin it must be copied into the
411 \&\fI${libdir}/bfd\-plugins\fR directory. For GCC based compilations
412 the linker plugin is called \fIliblto_plugin.so.0.0.0\fR. For Clang
413 based compilations it is called \fILLVMgold.so\fR. The GCC plugin
414 is always backwards compatible with earlier versions, so it is
415 sufficient to just copy the newest one.
416 .IP "\fB\-\-target\fR \fItarget\fR" 4
417 .IX Item "--target target"
418 The optional command-line switch \fB\-\-target\fR \fIbfdname\fR
419 specifies that the archive members are in an object code format
420 different from your system's default format. See
421 .IP "\fB\-\-output\fR \fIdirname\fR" 4
422 .IX Item "--output dirname"
423 The \fB\-\-output\fR option can be used to specify a path to a
424 directory into which archive members should be extracted. If this
425 option is not specified then the current directory will be used.
426 .Sp
427 Note \- although the presence of this option does imply a \fBx\fR
428 extraction operation that option must still be included on the command
429 line.
430 .IP "\fB\-\-record\-libdeps\fR \fIlibdeps\fR" 4
431 .IX Item "--record-libdeps libdeps"
432 The \fB\-\-record\-libdeps\fR option is identical to the \fBl\fR modifier,
433 just handled in long form.
434 .IP \fB\-\-thin\fR 4
435 .IX Item "--thin"
436 Make the specified \fIarchive\fR a \fIthin\fR archive. If it already
437 exists and is a regular archive, the existing members must be present
438 in the same directory as \fIarchive\fR.
439 .IP \fB@\fR\fIfile\fR 4
440 .IX Item "@file"
441 Read command-line options from \fIfile\fR. The options read are
442 inserted in place of the original @\fIfile\fR option. If \fIfile\fR
443 does not exist, or cannot be read, then the option will be treated
444 literally, and not removed.
445 .Sp
446 Options in \fIfile\fR are separated by whitespace. A whitespace
447 character may be included in an option by surrounding the entire
448 option in either single or double quotes. Any character (including a
449 backslash) may be included by prefixing the character to be included
450 with a backslash. The \fIfile\fR may itself contain additional
451 @\fIfile\fR options; any such options will be processed recursively.
452 .SH "SEE ALSO"
453 .IX Header "SEE ALSO"
454 \&\fBnm\fR\|(1), \fBranlib\fR\|(1), and the Info entries for \fIbinutils\fR.
455 .SH COPYRIGHT
456 .IX Header "COPYRIGHT"
457 Copyright (c) 1991\-2026 Free Software Foundation, Inc.
458 .PP
459 Permission is granted to copy, distribute and/or modify this document
460 under the terms of the GNU Free Documentation License, Version 1.3
461 or any later version published by the Free Software Foundation;
462 with no Invariant Sections, with no Front-Cover Texts, and with no
463 Back-Cover Texts. A copy of the license is included in the
464 section entitled "GNU Free Documentation License".