Penguin
Recent Changes
Annotated edit history of ar(1) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 AR
2 !!!AR
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 SEE ALSO
8 COPYRIGHT
9 ----
10 !!NAME
11
12
13 ar - create, modify, and extract from archives
14 !!SYNOPSIS
15
16
17 ar [[__-X32_64__] [[__-__]''p''[[''mod''
18 [[''relpos''] [[''count'']] ''archive''
19 [[''member''...]
20 !!DESCRIPTION
21
22
23 The GNU __ar__ program creates, modifies,
24 and extracts from archives. An ''archive'' is a single
25 file holding a collection of other files in a structure that
26 makes it possible to retrieve the original individual files
27 (called ''members'' of the archive).
28
29
30 The original files' contents, mode (permissions), timestamp,
31 owner, and group are preserved in the archive, and can be
32 restored on extraction.
33
34
35 GNU __ar__ can maintain archives whose
36 members have names of any length; however, depending on how
37 __ar__ is configured on your system, a limit on
38 member-name length may be imposed for compatibility with
39 archive formats maintained with other tools. If it exists,
40 the limit is often 15 characters (typical of formats related
41 to a.out) or 16 characters (typical of formats related to
42 coff).
43
44
45 __ar__ is considered a binary utility because archives of
46 this sort are most often used as ''libraries'' holding
47 commonly needed subroutines.
48
49
50 __ar__ creates an index to the symbols defined in
51 relocatable object modules in the archive when you specify
52 the modifier __s__. Once created, this index is updated
53 in the archive whenever __ar__ makes a change to its
54 contents (save for the __q__ update operation). An
55 archive with such an index speeds up linking to the library,
56 and allows routines in the library to call each other
57 without regard to their placement in the
58 archive.
59
60
61 You may use __nm -s__ or __nm --print-armap__ to list
62 this index table. If an archive lacks the table, another
63 form of __ar__ called __ranlib__ can be used to add
64 just the table.
65
66
67 GNU __ar__ is designed to be compatible
68 with two different facilities. You can control its activity
69 using command-line options, like the different varieties of
70 __ar__ on Unix systems; or, if you specify the single
71 command-line option __-M__, you can control it with a
72 script supplied via standard input, like the
73 MRI ``librarian'' program.
74 !!OPTIONS
75
76
77 GNU __ar__ allows you to mix the operation
78 code ''p'' and modifier flags ''mod'' in any order,
79 within the first command-line argument.
80
81
82 If you wish, you may begin the first command-line argument
83 with a dash.
84
85
86 The ''p'' keyletter specifies what operation to execute;
87 it may be any of the following, but you must specify only
88 one of them:
89
90
91 __d__
92
93
94 ''Delete'' modules from the archive. Specify the names of
95 modules to be deleted as ''member''...; the archive is
96 untouched if you specify no files to delete.
97
98
99 If you specify the __v__ modifier, __ar__ lists each
100 module as it is deleted.
101
102
103 __m__
104
105
106 Use this operation to ''move'' members in an
107 archive.
108
109
110 The ordering of members in an archive can make a difference
111 in how programs are linked using the library, if a symbol is
112 defined in more than one member.
113
114
115 If no modifiers are used with m, any members you
116 name in the ''member'' arguments are moved to the
117 ''end'' of the archive; you can use the __a__,
118 __b__, or __i__ modifiers to move them to a specified
119 place instead.
120
121
122 __p__
123
124
125 ''Print'' the specified members of the archive, to the
126 standard output file. If the __v__ modifier is specified,
127 show the member name before copying its contents to standard
128 output.
129
130
131 If you specify no ''member'' arguments, all the files in
132 the archive are printed.
133
134
135 __q__
136
137
138 ''Quick append''; Historically, add the files
139 ''member''... to the end of ''archive'', without
140 checking for replacement.
141
142
143 The modifiers __a__, __b__, and __i__ do ''not''
144 affect this operation; new members are always placed at the
145 end of the archive.
146
147
148 The modifier __v__ makes __ar__ list each file as it
149 is appended.
150
151
152 Since the point of this operation is speed, the archive's
153 symbol table index is not updated, even if it already
154 existed; you can use __ar s__ or __ranlib__ explicitly
155 to update the symbol table index.
156
157
158 However, too many different systems assume quick append
159 rebuilds the index, so GNU ar implements
160 q as a synonym for r.
161
162
163 __r__
164
165
166 Insert the files ''member''... into ''archive'' (with
167 ''replacement''). This operation differs from __q__ in
168 that any previously existing members are deleted if their
169 names match those being added.
170
171
172 If one of the files named in ''member''... does not
173 exist, __ar__ displays an error message, and leaves
174 undisturbed any existing members of the archive matching
175 that name.
176
177
178 By default, new members are added at the end of the file;
179 but you may use one of the modifiers __a__, __b__, or
180 __i__ to request placement relative to some existing
181 member.
182
183
184 The modifier __v__ used with this operation elicits a
185 line of output for each file inserted, along with one of the
186 letters __a__ or __r__ to indicate whether the file
187 was appended (no old member deleted) or
188 replaced.
189
190
191 __t__
192
193
194 Display a ''table'' listing the contents of
195 ''archive'', or those of the files listed in
196 ''member''... that are present in the archive. Normally
197 only the member name is shown; if you also want to see the
198 modes (permissions), timestamp, owner, group, and size, you
199 can request that by also specifying the __v__
200 modifier.
201
202
203 If you do not specify a ''member'', all files in the
204 archive are listed.
205
206
207 If there is more than one file with the same name (say,
208 __fie__) in an archive (say __b.a__), __ar t b.a
209 fie__ lists only the first instance; to see them all, you
210 must ask for a complete listing---in our example, __ar t
211 b.a__.
212
213
214 __x__
215
216
217 ''Extract'' members (named ''member'') from the
218 archive. You can use the __v__ modifier with this
219 operation, to request that __ar__ list each name as it
220 extracts it.
221
222
223 If you do not specify a ''member'', all files in the
224 archive are extracted.
225
226
227 A number of modifiers (''mod'') may immediately follow
228 the ''p'' keyletter, to specify variations on an
229 operation's behavior:
230
231
232 __a__
233
234
235 Add new files ''after'' an existing member of the
236 archive. If you use the modifier __a__, the name of an
237 existing archive member must be present as the ''relpos''
238 argument, before the ''archive''
239 specification.
240
241
242 __b__
243
244
245 Add new files ''before'' an existing member of the
246 archive. If you use the modifier __b__, the name of an
247 existing archive member must be present as the ''relpos''
248 argument, before the ''archive'' specification. (same as
249 __i__).
250
251
252 __c__
253
254
255 ''Create'' the archive. The specified ''archive'' is
256 always created if it did not exist, when you request an
257 update. But a warning is issued unless you specify in
258 advance that you expect to create it, by using this
259 modifier.
260
261
262 __f__
263
264
265 Truncate names in the archive. GNU __ar__
266 will normally permit file names of any length. This will
267 cause it to create archives which are not compatible with
268 the native __ar__ program on some systems. If this is a
269 concern, the __f__ modifier may be used to truncate file
270 names when putting them in the archive.
271
272
273 __i__
274
275
276 Insert new files ''before'' an existing member of the
277 archive. If you use the modifier __i__, the name of an
278 existing archive member must be present as the ''relpos''
279 argument, before the ''archive'' specification. (same as
280 __b__).
281
282
283 __l__
284
285
286 This modifier is accepted but not used.
287
288
289 __N__
290
291
292 Uses the ''count'' parameter. This is used if there are
293 multiple entries in the archive with the same name. Extract
294 or delete instance ''count'' of the given name from the
295 archive.
296
297
298 __o__
299
300
301 Preserve the ''original'' dates of members when
302 extracting them. If you do not specify this modifier, files
303 extracted from the archive are stamped with the time of
304 extraction.
305
306
307 __P__
308
309
310 Use the full path name when matching names in the archive.
311 GNU __ar__ can not create an archive with
312 a full path name (such archives are not POSIX
313 complaint), but other archive creators can. This option will
314 cause GNU __ar__ to match file names using
315 a complete path name, which can be convenient when
316 extracting a single file from an archive created by another
317 tool.
318
319
320 __s__
321
322
323 Write an object-file index into the archive, or update an
324 existing one, even if no other change is made to the
325 archive. You may use this modifier flag either with any
326 operation, or alone. Running __ar s__ on an archive is
327 equivalent to running __ranlib__ on it.
328
329
330 __S__
331
332
333 Do not generate an archive symbol table. This can speed up
334 building a large library in several steps. The resulting
335 archive can not be used with the linker. In order to build a
336 symbol table, you must omit the __S__ modifier on the
337 last execution of __ar__, or you must run __ranlib__
338 on the archive.
339
340
341 __u__
342
343
344 Normally, __ar r__... inserts all files listed into the
345 archive. If you would like to insert ''only'' those of
346 the files you list that are newer than existing members of
347 the same names, use this modifier. The __u__ modifier is
348 allowed only for the operation __r__ (replace). In
349 particular, the combination __qu__ is not allowed, since
350 checking the timestamps would lose any speed advantage from
351 the operation __q__.
352
353
354 __v__
355
356
357 This modifier requests the ''verbose'' version of an
358 operation. Many operations display additional information,
359 such as filenames processed, when the modifier __v__ is
360 appended.
361
362
363 __V__
364
365
366 This modifier shows the version number of
367 __ar__.
368
369
370 __ar__ ignores an initial option spelt __-X32_64__,
371 for compatibility with AIX . The behaviour
372 produced by this option is the default for
373 GNU __ar__. __ar__ does not support any
374 of the other __-X__ options; in particular, it does not
375 support __-X32__ which is the default for
376 AIX __ar__.
377 !!SEE ALSO
378
379
380 nm(1), ranlib(1), and the Info entries for
381 ''binutils''.
382 !!COPYRIGHT
383
384
385 Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000,
386 2001, 2002 Free Software Foundation, Inc.
387
388
389 Permission is granted to copy, distribute and/or modify this
390 document under the terms of the GNU Free
391 Documentation License, Version 1.1 or any later version
392 published by the Free Software Foundation; with no Invariant
393 Sections, with no Front-Cover Texts, and with no Back-Cover
394 Texts. A copy of the license is included in the section
395 entitled `` GNU Free Documentation
396 License''.
397 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.