1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
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. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, 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 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
67 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
68 .\" Fear. Run. Save yourself. No user-serviceable parts.
69 . \" fudge factors for nroff and troff
78 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
84 . \" simple accents for nroff and troff
94 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
95 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
96 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
97 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
98 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
99 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101 . \" troff and (daisy-wheel) nroff accents
102 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
103 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
104 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
105 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
106 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
107 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
108 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
109 .ds ae a\h'-(\w'a'u*4/10)'e
110 .ds Ae A\h'-(\w'A'u*4/10)'E
111 . \" corrections for vroff
112 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
113 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
114 . \" for low resolution devices (crt and lpr)
115 .if \n(.H>23 .if \n(.V>19 \
128 .\" ========================================================================
131 .TH AR 1 "2008-09-10" "binutils-2.18.90" "GNU Development Tools"
133 ar \- create, modify, and extract from archives
135 .IX Header "SYNOPSIS"
136 ar [\fB\-X32_64\fR] [\fB\-\fR]\fIp\fR[\fImod\fR [\fIrelpos\fR] [\fIcount\fR]] \fIarchive\fR [\fImember\fR...]
138 .IX Header "DESCRIPTION"
139 The \s-1GNU\s0 \fBar\fR program creates, modifies, and extracts from
140 archives. An \fIarchive\fR is a single file holding a collection of
141 other files in a structure that makes it possible to retrieve
142 the original individual files (called \fImembers\fR of the archive).
144 The original files' contents, mode (permissions), timestamp, owner, and
145 group are preserved in the archive, and can be restored on
148 \&\s-1GNU\s0 \fBar\fR can maintain archives whose members have names of any
149 length; however, depending on how \fBar\fR is configured on your
150 system, a limit on member-name length may be imposed for compatibility
151 with archive formats maintained with other tools. If it exists, the
152 limit is often 15 characters (typical of formats related to a.out) or 16
153 characters (typical of formats related to coff).
155 \&\fBar\fR is considered a binary utility because archives of this sort
156 are most often used as \fIlibraries\fR holding commonly needed
159 \&\fBar\fR creates an index to the symbols defined in relocatable
160 object modules in the archive when you specify the modifier \fBs\fR.
161 Once created, this index is updated in the archive whenever \fBar\fR
162 makes a change to its contents (save for the \fBq\fR update operation).
163 An archive with such an index speeds up linking to the library, and
164 allows routines in the library to call each other without regard to
165 their placement in the archive.
167 You may use \fBnm \-s\fR or \fBnm \-\-print\-armap\fR to list this index
168 table. If an archive lacks the table, another form of \fBar\fR called
169 \&\fBranlib\fR can be used to add just the table.
171 \&\s-1GNU\s0 \fBar\fR can optionally create a \fIthin\fR archive,
172 which contains a symbol index and references to the original copies
173 of the member files of the archives. Such an archive is useful
174 for building libraries for use within a local build, where the
175 relocatable objects are expected to remain available, and copying the
176 contents of each object would only waste time and space. Thin archives
177 are also \fIflattened\fR, so that adding one or more archives to a
178 thin archive will add the elements of the nested archive individually.
179 The paths to the elements of the archive are stored relative to the
182 \&\s-1GNU\s0 \fBar\fR is designed to be compatible with two different
183 facilities. You can control its activity using command-line options,
184 like the different varieties of \fBar\fR on Unix systems; or, if you
185 specify the single command-line option \fB\-M\fR, you can control it
186 with a script supplied via standard input, like the \s-1MRI\s0 \*(L"librarian\*(R"
190 \&\s-1GNU\s0 \fBar\fR allows you to mix the operation code \fIp\fR and modifier
191 flags \fImod\fR in any order, within the first command-line argument.
193 If you wish, you may begin the first command-line argument with a
196 The \fIp\fR keyletter specifies what operation to execute; it may be
197 any of the following, but you must specify only one of them:
200 \&\fIDelete\fR modules from the archive. Specify the names of modules to
201 be deleted as \fImember\fR...; the archive is untouched if you
202 specify no files to delete.
204 If you specify the \fBv\fR modifier, \fBar\fR lists each module
208 Use this operation to \fImove\fR members in an archive.
210 The ordering of members in an archive can make a difference in how
211 programs are linked using the library, if a symbol is defined in more
214 If no modifiers are used with \f(CW\*(C`m\*(C'\fR, any members you name in the
215 \&\fImember\fR arguments are moved to the \fIend\fR of the archive;
216 you can use the \fBa\fR, \fBb\fR, or \fBi\fR modifiers to move them to a
217 specified place instead.
220 \&\fIPrint\fR the specified members of the archive, to the standard
221 output file. If the \fBv\fR modifier is specified, show the member
222 name before copying its contents to standard output.
224 If you specify no \fImember\fR arguments, all the files in the archive are
228 \&\fIQuick append\fR; Historically, add the files \fImember\fR... to the end of
229 \&\fIarchive\fR, without checking for replacement.
231 The modifiers \fBa\fR, \fBb\fR, and \fBi\fR do \fInot\fR affect this
232 operation; new members are always placed at the end of the archive.
234 The modifier \fBv\fR makes \fBar\fR list each file as it is appended.
236 Since the point of this operation is speed, the archive's symbol table
237 index is not updated, even if it already existed; you can use \fBar s\fR or
238 \&\fBranlib\fR explicitly to update the symbol table index.
240 However, too many different systems assume quick append rebuilds the
241 index, so \s-1GNU\s0 \fBar\fR implements \fBq\fR as a synonym for \fBr\fR.
244 Insert the files \fImember\fR... into \fIarchive\fR (with
245 \&\fIreplacement\fR). This operation differs from \fBq\fR in that any
246 previously existing members are deleted if their names match those being
249 If one of the files named in \fImember\fR... does not exist, \fBar\fR
250 displays an error message, and leaves undisturbed any existing members
251 of the archive matching that name.
253 By default, new members are added at the end of the file; but you may
254 use one of the modifiers \fBa\fR, \fBb\fR, or \fBi\fR to request
255 placement relative to some existing member.
257 The modifier \fBv\fR used with this operation elicits a line of
258 output for each file inserted, along with one of the letters \fBa\fR or
259 \&\fBr\fR to indicate whether the file was appended (no old member
260 deleted) or replaced.
263 Display a \fItable\fR listing the contents of \fIarchive\fR, or those
264 of the files listed in \fImember\fR... that are present in the
265 archive. Normally only the member name is shown; if you also want to
266 see the modes (permissions), timestamp, owner, group, and size, you can
267 request that by also specifying the \fBv\fR modifier.
269 If you do not specify a \fImember\fR, all files in the archive
272 If there is more than one file with the same name (say, \fBfie\fR) in
273 an archive (say \fBb.a\fR), \fBar t b.a fie\fR lists only the
274 first instance; to see them all, you must ask for a complete
275 listing\-\-\-in our example, \fBar t b.a\fR.
278 \&\fIExtract\fR members (named \fImember\fR) from the archive. You can
279 use the \fBv\fR modifier with this operation, to request that
280 \&\fBar\fR list each name as it extracts it.
282 If you do not specify a \fImember\fR, all files in the archive
285 Files cannot be extracted from a thin archive.
287 A number of modifiers (\fImod\fR) may immediately follow the \fIp\fR
288 keyletter, to specify variations on an operation's behavior:
291 Add new files \fIafter\fR an existing member of the
292 archive. If you use the modifier \fBa\fR, the name of an existing archive
293 member must be present as the \fIrelpos\fR argument, before the
294 \&\fIarchive\fR specification.
297 Add new files \fIbefore\fR an existing member of the
298 archive. If you use the modifier \fBb\fR, the name of an existing archive
299 member must be present as the \fIrelpos\fR argument, before the
300 \&\fIarchive\fR specification. (same as \fBi\fR).
303 \&\fICreate\fR the archive. The specified \fIarchive\fR is always
304 created if it did not exist, when you request an update. But a warning is
305 issued unless you specify in advance that you expect to create it, by
309 Truncate names in the archive. \s-1GNU\s0 \fBar\fR will normally permit file
310 names of any length. This will cause it to create archives which are
311 not compatible with the native \fBar\fR program on some systems. If
312 this is a concern, the \fBf\fR modifier may be used to truncate file
313 names when putting them in the archive.
316 Insert new files \fIbefore\fR an existing member of the
317 archive. If you use the modifier \fBi\fR, the name of an existing archive
318 member must be present as the \fIrelpos\fR argument, before the
319 \&\fIarchive\fR specification. (same as \fBb\fR).
322 This modifier is accepted but not used.
325 Uses the \fIcount\fR parameter. This is used if there are multiple
326 entries in the archive with the same name. Extract or delete instance
327 \&\fIcount\fR of the given name from the archive.
330 Preserve the \fIoriginal\fR dates of members when extracting them. If
331 you do not specify this modifier, files extracted from the archive
332 are stamped with the time of extraction.
335 Use the full path name when matching names in the archive. \s-1GNU\s0
336 \&\fBar\fR can not create an archive with a full path name (such archives
337 are not \s-1POSIX\s0 complaint), but other archive creators can. This option
338 will cause \s-1GNU\s0 \fBar\fR to match file names using a complete path
339 name, which can be convenient when extracting a single file from an
340 archive created by another tool.
343 Write an object-file index into the archive, or update an existing one,
344 even if no other change is made to the archive. You may use this modifier
345 flag either with any operation, or alone. Running \fBar s\fR on an
346 archive is equivalent to running \fBranlib\fR on it.
349 Do not generate an archive symbol table. This can speed up building a
350 large library in several steps. The resulting archive can not be used
351 with the linker. In order to build a symbol table, you must omit the
352 \&\fBS\fR modifier on the last execution of \fBar\fR, or you must run
353 \&\fBranlib\fR on the archive.
356 Make the specified \fIarchive\fR a \fIthin\fR archive. If it already
357 exists and is a regular archive, the existing members must be present
358 in the same directory as \fIarchive\fR.
361 Normally, \fBar r\fR... inserts all files
362 listed into the archive. If you would like to insert \fIonly\fR those
363 of the files you list that are newer than existing members of the same
364 names, use this modifier. The \fBu\fR modifier is allowed only for the
365 operation \fBr\fR (replace). In particular, the combination \fBqu\fR is
366 not allowed, since checking the timestamps would lose any speed
367 advantage from the operation \fBq\fR.
370 This modifier requests the \fIverbose\fR version of an operation. Many
371 operations display additional information, such as filenames processed,
372 when the modifier \fBv\fR is appended.
375 This modifier shows the version number of \fBar\fR.
377 \&\fBar\fR ignores an initial option spelt \fB\-X32_64\fR, for
378 compatibility with \s-1AIX\s0. The behaviour produced by this option is the
379 default for \s-1GNU\s0 \fBar\fR. \fBar\fR does not support any of the other
380 \&\fB\-X\fR options; in particular, it does not support \fB\-X32\fR
381 which is the default for \s-1AIX\s0 \fBar\fR.
382 .IP "\fB@\fR\fIfile\fR" 4
384 Read command-line options from \fIfile\fR. The options read are
385 inserted in place of the original @\fIfile\fR option. If \fIfile\fR
386 does not exist, or cannot be read, then the option will be treated
387 literally, and not removed.
389 Options in \fIfile\fR are separated by whitespace. A whitespace
390 character may be included in an option by surrounding the entire
391 option in either single or double quotes. Any character (including a
392 backslash) may be included by prefixing the character to be included
393 with a backslash. The \fIfile\fR may itself contain additional
394 @\fIfile\fR options; any such options will be processed recursively.
396 .IX Header "SEE ALSO"
397 \&\fInm\fR\|(1), \fIranlib\fR\|(1), and the Info entries for \fIbinutils\fR.
399 .IX Header "COPYRIGHT"
400 Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
401 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
403 Permission is granted to copy, distribute and/or modify this document
404 under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.2
405 or any later version published by the Free Software Foundation;
406 with no Invariant Sections, with no Front-Cover Texts, and with no
407 Back-Cover Texts. A copy of the license is included in the
408 section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
OSDN Git Service
