1 .\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
9 .de Vb \" Begin verbatim text
14 .de Ve \" End verbatim text
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
49 .\" If the F register is turned on, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD. Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
54 .\" Avoid warning from groff about undefined register 'F'.
58 .if \n(.g .if rF .nr rF 1
59 .if (\n(rF:(\n(.g==0)) \{
62 . tm Index:\\$1\t\\n%\t"\\$2"
72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
73 .\" Fear. Run. Save yourself. No user-serviceable parts.
74 . \" fudge factors for nroff and troff
83 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
89 . \" simple accents for nroff and troff
99 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
100 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
101 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
102 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
103 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
104 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
106 . \" troff and (daisy-wheel) nroff accents
107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
114 .ds ae a\h'-(\w'a'u*4/10)'e
115 .ds Ae A\h'-(\w'A'u*4/10)'E
116 . \" corrections for vroff
117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
119 . \" for low resolution devices (crt and lpr)
120 .if \n(.H>23 .if \n(.V>19 \
133 .\" ========================================================================
136 .TH AR 1 "2014-12-23" "binutils-2.25" "GNU Development Tools"
137 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
138 .\" way too many mistakes in technical documents.
142 ar \- create, modify, and extract from archives
144 .IX Header "SYNOPSIS"
145 ar [\fB\-X32_64\fR] [\fB\-\fR]\fIp\fR[\fImod\fR] [\fB\-\-plugin\fR \fIname\fR] [\fB\-\-target\fR \fIbfdname\fR] [\fIrelpos\fR] [\fIcount\fR] \fIarchive\fR [\fImember\fR...]
147 .IX Header "DESCRIPTION"
148 The \s-1GNU \s0\fBar\fR program creates, modifies, and extracts from
149 archives. An \fIarchive\fR is a single file holding a collection of
150 other files in a structure that makes it possible to retrieve
151 the original individual files (called \fImembers\fR of the archive).
153 The original files' contents, mode (permissions), timestamp, owner, and
154 group are preserved in the archive, and can be restored on
157 \&\s-1GNU \s0\fBar\fR can maintain archives whose members have names of any
158 length; however, depending on how \fBar\fR is configured on your
159 system, a limit on member-name length may be imposed for compatibility
160 with archive formats maintained with other tools. If it exists, the
161 limit is often 15 characters (typical of formats related to a.out) or 16
162 characters (typical of formats related to coff).
164 \&\fBar\fR is considered a binary utility because archives of this sort
165 are most often used as \fIlibraries\fR holding commonly needed
168 \&\fBar\fR creates an index to the symbols defined in relocatable
169 object modules in the archive when you specify the modifier \fBs\fR.
170 Once created, this index is updated in the archive whenever \fBar\fR
171 makes a change to its contents (save for the \fBq\fR update operation).
172 An archive with such an index speeds up linking to the library, and
173 allows routines in the library to call each other without regard to
174 their placement in the archive.
176 You may use \fBnm \-s\fR or \fBnm \-\-print\-armap\fR to list this index
177 table. If an archive lacks the table, another form of \fBar\fR called
178 \&\fBranlib\fR can be used to add just the table.
180 \&\s-1GNU \s0\fBar\fR can optionally create a \fIthin\fR archive,
181 which contains a symbol index and references to the original copies
182 of the member files of the archive. This is useful for building
183 libraries for use within a local build tree, where the relocatable
184 objects are expected to remain available, and copying the contents of
185 each object would only waste time and space.
187 An archive can either be \fIthin\fR or it can be normal. It cannot
188 be both at the same time. Once an archive is created its format
189 cannot be changed without first deleting it and then creating a new
190 archive in its place.
192 Thin archives are also \fIflattened\fR, so that adding one thin
193 archive to another thin archive does not nest it, as would happen with
194 a normal archive. Instead the elements of the first archive are added
195 individually to the second archive.
197 The paths to the elements of the archive are stored relative to the
198 archive itself. For security reasons absolute paths and paths with a
199 \&\f(CW\*(C`/../\*(C'\fR component are not allowed.
201 \&\s-1GNU \s0\fBar\fR is designed to be compatible with two different
202 facilities. You can control its activity using command-line options,
203 like the different varieties of \fBar\fR on Unix systems; or, if you
204 specify the single command-line option \fB\-M\fR, you can control it
205 with a script supplied via standard input, like the \s-1MRI \s0\*(L"librarian\*(R"
209 \&\s-1GNU \s0\fBar\fR allows you to mix the operation code \fIp\fR and modifier
210 flags \fImod\fR in any order, within the first command-line argument.
212 If you wish, you may begin the first command-line argument with a
215 The \fIp\fR keyletter specifies what operation to execute; it may be
216 any of the following, but you must specify only one of them:
219 \&\fIDelete\fR modules from the archive. Specify the names of modules to
220 be deleted as \fImember\fR...; the archive is untouched if you
221 specify no files to delete.
223 If you specify the \fBv\fR modifier, \fBar\fR lists each module
227 Use this operation to \fImove\fR members in an archive.
229 The ordering of members in an archive can make a difference in how
230 programs are linked using the library, if a symbol is defined in more
233 If no modifiers are used with \f(CW\*(C`m\*(C'\fR, any members you name in the
234 \&\fImember\fR arguments are moved to the \fIend\fR of the archive;
235 you can use the \fBa\fR, \fBb\fR, or \fBi\fR modifiers to move them to a
236 specified place instead.
239 \&\fIPrint\fR the specified members of the archive, to the standard
240 output file. If the \fBv\fR modifier is specified, show the member
241 name before copying its contents to standard output.
243 If you specify no \fImember\fR arguments, all the files in the archive are
247 \&\fIQuick append\fR; Historically, add the files \fImember\fR... to the end of
248 \&\fIarchive\fR, without checking for replacement.
250 The modifiers \fBa\fR, \fBb\fR, and \fBi\fR do \fInot\fR affect this
251 operation; new members are always placed at the end of the archive.
253 The modifier \fBv\fR makes \fBar\fR list each file as it is appended.
255 Since the point of this operation is speed, implementations of
256 \&\fBar\fR have the option of not updating the archive's symbol
257 table if one exists. Too many different systems however assume that
258 symbol tables are always up-to-date, so \s-1GNU \s0\fBar\fR will
259 rebuild the table even with a quick append.
261 Note \- \s-1GNU \s0\fBar\fR treats the command \fBqs\fR as a
262 synonym for \fBr\fR \- replacing already existing files in the
263 archive and appending new ones at the end.
266 Insert the files \fImember\fR... into \fIarchive\fR (with
267 \&\fIreplacement\fR). This operation differs from \fBq\fR in that any
268 previously existing members are deleted if their names match those being
271 If one of the files named in \fImember\fR... does not exist, \fBar\fR
272 displays an error message, and leaves undisturbed any existing members
273 of the archive matching that name.
275 By default, new members are added at the end of the file; but you may
276 use one of the modifiers \fBa\fR, \fBb\fR, or \fBi\fR to request
277 placement relative to some existing member.
279 The modifier \fBv\fR used with this operation elicits a line of
280 output for each file inserted, along with one of the letters \fBa\fR or
281 \&\fBr\fR to indicate whether the file was appended (no old member
282 deleted) or replaced.
285 Add an index to the archive, or update it if it already exists. Note
286 this command is an exception to the rule that there can only be one
287 command letter, as it is possible to use it as either a command or a
288 modifier. In either case it does the same thing.
291 Display a \fItable\fR listing the contents of \fIarchive\fR, or those
292 of the files listed in \fImember\fR... that are present in the
293 archive. Normally only the member name is shown; if you also want to
294 see the modes (permissions), timestamp, owner, group, and size, you can
295 request that by also specifying the \fBv\fR modifier.
297 If you do not specify a \fImember\fR, all files in the archive
300 If there is more than one file with the same name (say, \fBfie\fR) in
301 an archive (say \fBb.a\fR), \fBar t b.a fie\fR lists only the
302 first instance; to see them all, you must ask for a complete
303 listing\-\-\-in our example, \fBar t b.a\fR.
306 \&\fIExtract\fR members (named \fImember\fR) from the archive. You can
307 use the \fBv\fR modifier with this operation, to request that
308 \&\fBar\fR list each name as it extracts it.
310 If you do not specify a \fImember\fR, all files in the archive
313 Files cannot be extracted from a thin archive.
314 .IP "\fB\-\-help\fR" 4
316 Displays the list of command line options supported by \fBar\fR
318 .IP "\fB\-\-version\fR" 4
320 Displays the version information of \fBar\fR and then exits.
322 A number of modifiers (\fImod\fR) may immediately follow the \fIp\fR
323 keyletter, to specify variations on an operation's behavior:
326 Add new files \fIafter\fR an existing member of the
327 archive. If you use the modifier \fBa\fR, the name of an existing archive
328 member must be present as the \fIrelpos\fR argument, before the
329 \&\fIarchive\fR specification.
332 Add new files \fIbefore\fR an existing member of the
333 archive. If you use the modifier \fBb\fR, the name of an existing archive
334 member must be present as the \fIrelpos\fR argument, before the
335 \&\fIarchive\fR specification. (same as \fBi\fR).
338 \&\fICreate\fR the archive. The specified \fIarchive\fR is always
339 created if it did not exist, when you request an update. But a warning is
340 issued unless you specify in advance that you expect to create it, by
344 Operate in \fIdeterministic\fR mode. When adding files and the archive
345 index use zero for UIDs, GIDs, timestamps, and use consistent file modes
346 for all files. When this option is used, if \fBar\fR is used with
347 identical options and identical input files, multiple runs will create
348 identical output files regardless of the input files' owners, groups,
349 file modes, or modification times.
351 If \fIbinutils\fR was configured with
352 \&\fB\-\-enable\-deterministic\-archives\fR, then this mode is on by default.
353 It can be disabled with the \fBU\fR modifier, below.
356 Truncate names in the archive. \s-1GNU \s0\fBar\fR will normally permit file
357 names of any length. This will cause it to create archives which are
358 not compatible with the native \fBar\fR program on some systems. If
359 this is a concern, the \fBf\fR modifier may be used to truncate file
360 names when putting them in the archive.
363 Insert new files \fIbefore\fR an existing member of the
364 archive. If you use the modifier \fBi\fR, the name of an existing archive
365 member must be present as the \fIrelpos\fR argument, before the
366 \&\fIarchive\fR specification. (same as \fBb\fR).
369 This modifier is accepted but not used.
372 Uses the \fIcount\fR parameter. This is used if there are multiple
373 entries in the archive with the same name. Extract or delete instance
374 \&\fIcount\fR of the given name from the archive.
377 Preserve the \fIoriginal\fR dates of members when extracting them. If
378 you do not specify this modifier, files extracted from the archive
379 are stamped with the time of extraction.
382 Use the full path name when matching names in the archive. \s-1GNU
383 \&\s0\fBar\fR can not create an archive with a full path name (such archives
384 are not \s-1POSIX\s0 complaint), but other archive creators can. This option
385 will cause \s-1GNU \s0\fBar\fR to match file names using a complete path
386 name, which can be convenient when extracting a single file from an
387 archive created by another tool.
390 Write an object-file index into the archive, or update an existing one,
391 even if no other change is made to the archive. You may use this modifier
392 flag either with any operation, or alone. Running \fBar s\fR on an
393 archive is equivalent to running \fBranlib\fR on it.
396 Do not generate an archive symbol table. This can speed up building a
397 large library in several steps. The resulting archive can not be used
398 with the linker. In order to build a symbol table, you must omit the
399 \&\fBS\fR modifier on the last execution of \fBar\fR, or you must run
400 \&\fBranlib\fR on the archive.
403 Make the specified \fIarchive\fR a \fIthin\fR archive. If it already
404 exists and is a regular archive, the existing members must be present
405 in the same directory as \fIarchive\fR.
408 Normally, \fBar r\fR... inserts all files
409 listed into the archive. If you would like to insert \fIonly\fR those
410 of the files you list that are newer than existing members of the same
411 names, use this modifier. The \fBu\fR modifier is allowed only for the
412 operation \fBr\fR (replace). In particular, the combination \fBqu\fR is
413 not allowed, since checking the timestamps would lose any speed
414 advantage from the operation \fBq\fR.
417 Do \fInot\fR operate in \fIdeterministic\fR mode. This is the inverse
418 of the \fBD\fR modifier, above: added files and the archive index will
419 get their actual \s-1UID, GID,\s0 timestamp, and file mode values.
421 This is the default unless \fIbinutils\fR was configured with
422 \&\fB\-\-enable\-deterministic\-archives\fR.
425 This modifier requests the \fIverbose\fR version of an operation. Many
426 operations display additional information, such as filenames processed,
427 when the modifier \fBv\fR is appended.
430 This modifier shows the version number of \fBar\fR.
432 \&\fBar\fR ignores an initial option spelt \fB\-X32_64\fR, for
433 compatibility with \s-1AIX. \s0 The behaviour produced by this option is the
434 default for \s-1GNU \s0\fBar\fR. \fBar\fR does not support any of the other
435 \&\fB\-X\fR options; in particular, it does not support \fB\-X32\fR
436 which is the default for \s-1AIX \s0\fBar\fR.
438 The optional command line switch \fB\-\-plugin\fR \fIname\fR causes
439 \&\fBar\fR to load the plugin called \fIname\fR which adds support
440 for more file formats. This option is only available if the toolchain
441 has been built with plugin support enabled.
443 The optional command line switch \fB\-\-target\fR \fIbfdname\fR
444 specifies that the archive members are in an object code format
445 different from your system's default format. See
446 .IP "\fB@\fR\fIfile\fR" 4
448 Read command-line options from \fIfile\fR. The options read are
449 inserted in place of the original @\fIfile\fR option. If \fIfile\fR
450 does not exist, or cannot be read, then the option will be treated
451 literally, and not removed.
453 Options in \fIfile\fR are separated by whitespace. A whitespace
454 character may be included in an option by surrounding the entire
455 option in either single or double quotes. Any character (including a
456 backslash) may be included by prefixing the character to be included
457 with a backslash. The \fIfile\fR may itself contain additional
458 @\fIfile\fR options; any such options will be processed recursively.
460 .IX Header "SEE ALSO"
461 \&\fInm\fR\|(1), \fIranlib\fR\|(1), and the Info entries for \fIbinutils\fR.
463 .IX Header "COPYRIGHT"
464 Copyright (c) 1991\-2014 Free Software Foundation, Inc.
466 Permission is granted to copy, distribute and/or modify this document
467 under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
468 or any later version published by the Free Software Foundation;
469 with no Invariant Sections, with no Front-Cover Texts, and with no
470 Back-Cover Texts. A copy of the license is included in the
471 section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
projects / dragonfly.git / blob