1 .\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
29 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" Escape single quotes in literal strings from groff's Unicode transform.
55 .\" If the F register is turned on, we'll generate index entries on stderr for
56 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
57 .\" entries marked with X<> in POD. Of course, you'll have to process the
58 .\" output yourself in some meaningful fashion.
61 . tm Index:\\$1\t\\n%\t"\\$2"
71 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
72 .\" Fear. Run. Save yourself. No user-serviceable parts.
73 . \" fudge factors for nroff and troff
82 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
88 . \" simple accents for nroff and troff
98 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
99 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
100 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
101 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
102 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
103 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
105 . \" troff and (daisy-wheel) nroff accents
106 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
107 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
108 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
109 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
110 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
111 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
112 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
113 .ds ae a\h'-(\w'a'u*4/10)'e
114 .ds Ae A\h'-(\w'A'u*4/10)'E
115 . \" corrections for vroff
116 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
117 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
118 . \" for low resolution devices (crt and lpr)
119 .if \n(.H>23 .if \n(.V>19 \
132 .\" ========================================================================
135 .TH AR 1 "2011-06-27" "binutils-2.21.1" "GNU Development Tools"
136 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
137 .\" way too many mistakes in technical documents.
141 ar \- create, modify, and extract from archives
143 .IX Header "SYNOPSIS"
144 ar [\fB\-\-plugin\fR \fIname\fR] [\fB\-X32_64\fR] [\fB\-\fR]\fIp\fR[\fImod\fR [\fIrelpos\fR] [\fIcount\fR]] \fIarchive\fR [\fImember\fR...]
146 .IX Header "DESCRIPTION"
147 The \s-1GNU\s0 \fBar\fR program creates, modifies, and extracts from
148 archives. An \fIarchive\fR is a single file holding a collection of
149 other files in a structure that makes it possible to retrieve
150 the original individual files (called \fImembers\fR of the archive).
152 The original files' contents, mode (permissions), timestamp, owner, and
153 group are preserved in the archive, and can be restored on
156 \&\s-1GNU\s0 \fBar\fR can maintain archives whose members have names of any
157 length; however, depending on how \fBar\fR is configured on your
158 system, a limit on member-name length may be imposed for compatibility
159 with archive formats maintained with other tools. If it exists, the
160 limit is often 15 characters (typical of formats related to a.out) or 16
161 characters (typical of formats related to coff).
163 \&\fBar\fR is considered a binary utility because archives of this sort
164 are most often used as \fIlibraries\fR holding commonly needed
167 \&\fBar\fR creates an index to the symbols defined in relocatable
168 object modules in the archive when you specify the modifier \fBs\fR.
169 Once created, this index is updated in the archive whenever \fBar\fR
170 makes a change to its contents (save for the \fBq\fR update operation).
171 An archive with such an index speeds up linking to the library, and
172 allows routines in the library to call each other without regard to
173 their placement in the archive.
175 You may use \fBnm \-s\fR or \fBnm \-\-print\-armap\fR to list this index
176 table. If an archive lacks the table, another form of \fBar\fR called
177 \&\fBranlib\fR can be used to add just the table.
179 \&\s-1GNU\s0 \fBar\fR can optionally create a \fIthin\fR archive,
180 which contains a symbol index and references to the original copies
181 of the member files of the archives. Such an archive is useful
182 for building libraries for use within a local build, where the
183 relocatable objects are expected to remain available, and copying the
184 contents of each object would only waste time and space. Thin archives
185 are also \fIflattened\fR, so that adding one or more archives to a
186 thin archive will add the elements of the nested archive individually.
187 The paths to the elements of the archive are stored relative to the
190 \&\s-1GNU\s0 \fBar\fR is designed to be compatible with two different
191 facilities. You can control its activity using command-line options,
192 like the different varieties of \fBar\fR on Unix systems; or, if you
193 specify the single command-line option \fB\-M\fR, you can control it
194 with a script supplied via standard input, like the \s-1MRI\s0 \*(L"librarian\*(R"
198 \&\s-1GNU\s0 \fBar\fR allows you to mix the operation code \fIp\fR and modifier
199 flags \fImod\fR in any order, within the first command-line argument.
201 If you wish, you may begin the first command-line argument with a
204 The \fIp\fR keyletter specifies what operation to execute; it may be
205 any of the following, but you must specify only one of them:
208 \&\fIDelete\fR modules from the archive. Specify the names of modules to
209 be deleted as \fImember\fR...; the archive is untouched if you
210 specify no files to delete.
212 If you specify the \fBv\fR modifier, \fBar\fR lists each module
216 Use this operation to \fImove\fR members in an archive.
218 The ordering of members in an archive can make a difference in how
219 programs are linked using the library, if a symbol is defined in more
222 If no modifiers are used with \f(CW\*(C`m\*(C'\fR, any members you name in the
223 \&\fImember\fR arguments are moved to the \fIend\fR of the archive;
224 you can use the \fBa\fR, \fBb\fR, or \fBi\fR modifiers to move them to a
225 specified place instead.
228 \&\fIPrint\fR the specified members of the archive, to the standard
229 output file. If the \fBv\fR modifier is specified, show the member
230 name before copying its contents to standard output.
232 If you specify no \fImember\fR arguments, all the files in the archive are
236 \&\fIQuick append\fR; Historically, add the files \fImember\fR... to the end of
237 \&\fIarchive\fR, without checking for replacement.
239 The modifiers \fBa\fR, \fBb\fR, and \fBi\fR do \fInot\fR affect this
240 operation; new members are always placed at the end of the archive.
242 The modifier \fBv\fR makes \fBar\fR list each file as it is appended.
244 Since the point of this operation is speed, the archive's symbol table
245 index is not updated, even if it already existed; you can use \fBar s\fR or
246 \&\fBranlib\fR explicitly to update the symbol table index.
248 However, too many different systems assume quick append rebuilds the
249 index, so \s-1GNU\s0 \fBar\fR implements \fBq\fR as a synonym for \fBr\fR.
252 Insert the files \fImember\fR... into \fIarchive\fR (with
253 \&\fIreplacement\fR). This operation differs from \fBq\fR in that any
254 previously existing members are deleted if their names match those being
257 If one of the files named in \fImember\fR... does not exist, \fBar\fR
258 displays an error message, and leaves undisturbed any existing members
259 of the archive matching that name.
261 By default, new members are added at the end of the file; but you may
262 use one of the modifiers \fBa\fR, \fBb\fR, or \fBi\fR to request
263 placement relative to some existing member.
265 The modifier \fBv\fR used with this operation elicits a line of
266 output for each file inserted, along with one of the letters \fBa\fR or
267 \&\fBr\fR to indicate whether the file was appended (no old member
268 deleted) or replaced.
271 Add an index to the archive, or update it if it already exists. Note
272 this command is an exception to the rule that there can only be one
273 command letter, as it is possible to use it as either a command or a
274 modifier. In either case it does the same thing.
277 Display a \fItable\fR listing the contents of \fIarchive\fR, or those
278 of the files listed in \fImember\fR... that are present in the
279 archive. Normally only the member name is shown; if you also want to
280 see the modes (permissions), timestamp, owner, group, and size, you can
281 request that by also specifying the \fBv\fR modifier.
283 If you do not specify a \fImember\fR, all files in the archive
286 If there is more than one file with the same name (say, \fBfie\fR) in
287 an archive (say \fBb.a\fR), \fBar t b.a fie\fR lists only the
288 first instance; to see them all, you must ask for a complete
289 listing\-\-\-in our example, \fBar t b.a\fR.
292 \&\fIExtract\fR members (named \fImember\fR) from the archive. You can
293 use the \fBv\fR modifier with this operation, to request that
294 \&\fBar\fR list each name as it extracts it.
296 If you do not specify a \fImember\fR, all files in the archive
299 Files cannot be extracted from a thin archive.
301 A number of modifiers (\fImod\fR) may immediately follow the \fIp\fR
302 keyletter, to specify variations on an operation's behavior:
305 Add new files \fIafter\fR an existing member of the
306 archive. If you use the modifier \fBa\fR, the name of an existing archive
307 member must be present as the \fIrelpos\fR argument, before the
308 \&\fIarchive\fR specification.
311 Add new files \fIbefore\fR an existing member of the
312 archive. If you use the modifier \fBb\fR, the name of an existing archive
313 member must be present as the \fIrelpos\fR argument, before the
314 \&\fIarchive\fR specification. (same as \fBi\fR).
317 \&\fICreate\fR the archive. The specified \fIarchive\fR is always
318 created if it did not exist, when you request an update. But a warning is
319 issued unless you specify in advance that you expect to create it, by
323 Operate in \fIdeterministic\fR mode. When adding files and the archive
324 index use zero for UIDs, GIDs, timestamps, and use consistent file modes
325 for all files. When this option is used, if \fBar\fR is used with
326 identical options and identical input files, multiple runs will create
327 identical output files regardless of the input files' owners, groups,
328 file modes, or modification times.
331 Truncate names in the archive. \s-1GNU\s0 \fBar\fR will normally permit file
332 names of any length. This will cause it to create archives which are
333 not compatible with the native \fBar\fR program on some systems. If
334 this is a concern, the \fBf\fR modifier may be used to truncate file
335 names when putting them in the archive.
338 Insert new files \fIbefore\fR an existing member of the
339 archive. If you use the modifier \fBi\fR, the name of an existing archive
340 member must be present as the \fIrelpos\fR argument, before the
341 \&\fIarchive\fR specification. (same as \fBb\fR).
344 This modifier is accepted but not used.
347 Uses the \fIcount\fR parameter. This is used if there are multiple
348 entries in the archive with the same name. Extract or delete instance
349 \&\fIcount\fR of the given name from the archive.
352 Preserve the \fIoriginal\fR dates of members when extracting them. If
353 you do not specify this modifier, files extracted from the archive
354 are stamped with the time of extraction.
357 Use the full path name when matching names in the archive. \s-1GNU\s0
358 \&\fBar\fR can not create an archive with a full path name (such archives
359 are not \s-1POSIX\s0 complaint), but other archive creators can. This option
360 will cause \s-1GNU\s0 \fBar\fR to match file names using a complete path
361 name, which can be convenient when extracting a single file from an
362 archive created by another tool.
365 Write an object-file index into the archive, or update an existing one,
366 even if no other change is made to the archive. You may use this modifier
367 flag either with any operation, or alone. Running \fBar s\fR on an
368 archive is equivalent to running \fBranlib\fR on it.
371 Do not generate an archive symbol table. This can speed up building a
372 large library in several steps. The resulting archive can not be used
373 with the linker. In order to build a symbol table, you must omit the
374 \&\fBS\fR modifier on the last execution of \fBar\fR, or you must run
375 \&\fBranlib\fR on the archive.
378 Make the specified \fIarchive\fR a \fIthin\fR archive. If it already
379 exists and is a regular archive, the existing members must be present
380 in the same directory as \fIarchive\fR.
383 Normally, \fBar r\fR... inserts all files
384 listed into the archive. If you would like to insert \fIonly\fR those
385 of the files you list that are newer than existing members of the same
386 names, use this modifier. The \fBu\fR modifier is allowed only for the
387 operation \fBr\fR (replace). In particular, the combination \fBqu\fR is
388 not allowed, since checking the timestamps would lose any speed
389 advantage from the operation \fBq\fR.
392 This modifier requests the \fIverbose\fR version of an operation. Many
393 operations display additional information, such as filenames processed,
394 when the modifier \fBv\fR is appended.
397 This modifier shows the version number of \fBar\fR.
399 \&\fBar\fR ignores an initial option spelt \fB\-X32_64\fR, for
400 compatibility with \s-1AIX\s0. The behaviour produced by this option is the
401 default for \s-1GNU\s0 \fBar\fR. \fBar\fR does not support any of the other
402 \&\fB\-X\fR options; in particular, it does not support \fB\-X32\fR
403 which is the default for \s-1AIX\s0 \fBar\fR.
405 The optional command line switch \fB\-\-plugin\fR \fIname\fR causes
406 \&\fBar\fR to load the plugin called \fIname\fR which adds support
407 for more file formats. This option is only available if the toolchain
408 has been built with plugin support enabled.
409 .IP "\fB@\fR\fIfile\fR" 4
411 Read command-line options from \fIfile\fR. The options read are
412 inserted in place of the original @\fIfile\fR option. If \fIfile\fR
413 does not exist, or cannot be read, then the option will be treated
414 literally, and not removed.
416 Options in \fIfile\fR are separated by whitespace. A whitespace
417 character may be included in an option by surrounding the entire
418 option in either single or double quotes. Any character (including a
419 backslash) may be included by prefixing the character to be included
420 with a backslash. The \fIfile\fR may itself contain additional
421 @\fIfile\fR options; any such options will be processed recursively.
423 .IX Header "SEE ALSO"
424 \&\fInm\fR\|(1), \fIranlib\fR\|(1), and the Info entries for \fIbinutils\fR.
426 .IX Header "COPYRIGHT"
427 Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
428 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
429 Free Software Foundation, Inc.
431 Permission is granted to copy, distribute and/or modify this document
432 under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
433 or any later version published by the Free Software Foundation;
434 with no Invariant Sections, with no Front-Cover Texts, and with no
435 Back-Cover Texts. A copy of the license is included in the
436 section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
tuxillo's projects / dragonfly.git / blob