Debian Codegraph @

upstream/opensuse-tumbleweed/man1/ar.1

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