Commit | Line | Data |
---|---|---|
0f6863a5 RP |
1 | .\" Copyright (c) 1991 Free Software Foundation |
2 | .\" See section COPYING for conditions for redistribution | |
3 | .\" $Id$ | |
4 | .TH ar 1 "5 November 1991" "cygnus support" "GNU Development Tools" | |
5 | .de BP | |
6 | .sp | |
7 | .ti \-.2i | |
8 | \(** | |
9 | .. | |
10 | ||
11 | .SH NAME | |
12 | ar\(em\&create, modify, and extract from archives. | |
13 | ||
14 | .SH SYNOPSIS | |
15 | .hy 0 | |
16 | .na | |
17 | .BR ar " [\|" "-" "\|]"\c | |
18 | .I pmod \c | |
19 | [\|\c | |
20 | .I membername\c | |
21 | \&\|] \c | |
22 | .I archive\c | |
23 | \& \c | |
24 | .I files\c | |
25 | \&.\|.\|. | |
26 | ||
27 | .ad b | |
28 | .hy 1 | |
29 | .SH DESCRIPTION | |
30 | The GNU \c | |
31 | .B ar\c | |
32 | \& program creates, modifies, and extracts from | |
33 | archives. An \c | |
34 | .I archive\c | |
35 | \& is a single file holding a collection of | |
36 | other files in a structure that makes it possible to retrieve | |
37 | the original individual files (called \c | |
38 | .I members\c | |
39 | \& of the archive). | |
40 | ||
41 | The original files' contents, mode (permissions), timestamp, owner, and | |
42 | group are preserved in the archive, and may be reconstituted on | |
43 | extraction. | |
44 | ||
45 | GNU \c | |
46 | .B ar\c | |
47 | \& can maintain archives whose members have names of any | |
48 | length; however, depending on how \c | |
49 | .B ar\c | |
50 | \& is configured on your | |
51 | system, a limit on member-name length may be imposed (for compatibility | |
52 | with archive formats maintained with other tools). If it exists, the | |
53 | limit is often 15 characters (typical of formats related to a.out) or 16 | |
54 | characters (typical of formats related to coff). | |
55 | ||
56 | \c | |
57 | .B ar\c | |
58 | \& is considered a binary utility because archives of this sort | |
59 | are most often used as \c | |
60 | .I libraries\c | |
61 | \& holding commonly needed | |
62 | subroutines. | |
63 | ||
64 | \c | |
65 | .B ar\c | |
66 | \& will create an index to the symbols defined in relocatable | |
67 | object modules in the archive when you specify the modifier `\|\c | |
68 | .B s\c | |
69 | \|'. | |
70 | Once created, this index is updated in the archive whenever \c | |
71 | .B ar\c | |
72 | \& | |
73 | makes a change to its contents (save for the `\|\c | |
74 | .B q\c | |
75 | \|' update operation). | |
76 | An archive with such an index speeds up linking to the library, and | |
77 | allows routines in the library to call each other without regard to | |
78 | their placement in the archive. | |
79 | ||
80 | You may use `\|\c | |
81 | .B nm \-s\c | |
82 | \|' or `\|\c | |
83 | .B nm +print-armap\c | |
84 | \|' to list this index | |
85 | table. If an archive lacks the table, another form of \c | |
86 | .B ar\c | |
87 | \& called | |
88 | \c | |
89 | .B ranlib\c | |
90 | \& can be used to add just the table. | |
91 | ||
92 | \c | |
93 | .B ar\c | |
94 | \& insists on at least two arguments to execute: one | |
95 | keyletter specifying the \c | |
96 | .I operation\c | |
97 | \& (optionally accompanied by other | |
98 | keyletters specifying \c | |
99 | .I modifiers\c | |
100 | \&), and the archive name to act on. | |
101 | ||
102 | Most operations can also accept further \c | |
103 | .I files\c | |
104 | \& arguments, | |
105 | specifying particular files to operate on. | |
106 | ||
107 | .SH OPTIONS | |
108 | GNU \c | |
109 | .B ar\c | |
110 | \& allows you to mix the operation code \c | |
111 | .I p\c | |
112 | \& and modifier | |
113 | flags \c | |
114 | .I mod\c | |
115 | \& in any order, within the first command-line argument. | |
116 | ||
117 | If you wish, you may begin the first command-line argument with a | |
118 | dash. | |
119 | ||
120 | The \c | |
121 | .I p\c | |
122 | \& keyletter specifies what operation to execute; it may be | |
123 | any of the following, but you must specify only one of them: | |
124 | ||
125 | .TP | |
126 | .B d | |
127 | \c | |
128 | .I Delete\c | |
129 | \& modules from the archive. Specify the names of modules to | |
130 | be deleted as \c | |
131 | .I files\c | |
132 | \&; the archive is untouched if you | |
133 | specify no files to delete. | |
134 | ||
135 | If you specify the `\|\c | |
136 | .B v\c | |
137 | \|' modifier, \c | |
138 | .B ar\c | |
139 | \& will list each module | |
140 | as it is deleted. | |
141 | ||
142 | .TP | |
143 | .B m | |
144 | Use this operation to \c | |
145 | .I move\c | |
146 | \& members in an archive. | |
147 | ||
148 | The ordering of members in an archive can make a difference in how | |
149 | programs are linked using the library, if a symbol is defined in more | |
150 | than one member. | |
151 | ||
152 | If no modifiers are used with \c | |
153 | .B m\c | |
154 | \&, any members you name in the | |
155 | \c | |
156 | .I files\c | |
157 | \& arguments are moved to the \c | |
158 | .I end\c | |
159 | \& of the archive; | |
160 | you can use the `\|\c | |
161 | .B a\c | |
162 | \|', `\|\c | |
163 | .B b\c | |
164 | \|', or `\|\c | |
165 | .B i\c | |
166 | \|' modifiers to move them to a | |
167 | specified place instead. | |
168 | ||
169 | .TP | |
170 | .B p | |
171 | \c | |
172 | .I Print\c | |
173 | \& the specified members of the archive, to the standard | |
174 | output file. If the `\|\c | |
175 | .B v\c | |
176 | \|' modifier is specified, show the member | |
177 | name before copying its contents to standard output. | |
178 | ||
179 | If you specify no \c | |
180 | .I files\c | |
181 | \&, all the files in the archive are printed. | |
182 | ||
183 | .TP | |
184 | .B q | |
185 | \c | |
186 | .I Quick append\c | |
187 | \&; add \c | |
188 | .I files\c | |
189 | \& to the end of \c | |
190 | .I archive\c | |
191 | \&, | |
192 | without checking for replacement. | |
193 | ||
194 | The modifiers `\|\c | |
195 | .B a\c | |
196 | \|', `\|\c | |
197 | .B b\c | |
198 | \|', and `\|\c | |
199 | .B i\c | |
200 | \|' do \c | |
201 | .I not\c | |
202 | \& affect this | |
203 | operation; new members are always placed at the end of the archive. | |
204 | ||
205 | The modifier `\|\c | |
206 | .B v\c | |
207 | \|' makes \c | |
208 | .B ar\c | |
209 | \& list each file as it is appended. | |
210 | ||
211 | Since the point of this operation is speed, the archive's symbol table | |
212 | index is not updated, even if it already existed; you can use `\|\c | |
213 | .B ar s\c | |
214 | \|' or | |
215 | \c | |
216 | .B ranlib\c | |
217 | \& explicitly to update the symbol table index. | |
218 | ||
219 | .TP | |
220 | .B r | |
221 | Insert \c | |
222 | .I files\c | |
223 | \& into \c | |
224 | .I archive\c | |
225 | \& (with \c | |
226 | .I replacement\c | |
227 | \&). This | |
228 | operation differs from `\|\c | |
229 | .B q\c | |
230 | \|' in that any previously existing members | |
231 | are deleted if their names match those being added. | |
232 | ||
233 | If one of the files named in \c | |
234 | .I files\c | |
235 | \& doesn't exist, \c | |
236 | .B ar\c | |
237 | \& | |
238 | displays an error message, and leaves undisturbed any existing members | |
239 | of the archive matching that name. | |
240 | ||
241 | By default, new members are added at the end of the file; but you may | |
242 | use one of the modifiers `\|\c | |
243 | .B a\c | |
244 | \|', `\|\c | |
245 | .B b\c | |
246 | \|', or `\|\c | |
247 | .B i\c | |
248 | \|' to request | |
249 | placement relative to some existing member. | |
250 | ||
251 | The modifier `\|\c | |
252 | .B v\c | |
253 | \|' used with this operation elicits a line of | |
254 | output for each file inserted, along with one of the letters `\|\c | |
255 | .B a\c | |
256 | \|' or | |
257 | `\|\c | |
258 | .B r\c | |
259 | \|' to indicate whether the file was appended (no old member | |
260 | deleted) or replaced. | |
261 | ||
262 | .TP | |
263 | .B t | |
264 | Display a \c | |
265 | .I table\c | |
266 | \& listing the contents of \c | |
267 | .I archive\c | |
268 | \&, or those | |
269 | of the files listed in \c | |
270 | .I files\c | |
271 | \& that are present in the | |
272 | archive. Normally only the member name is shown; if you also want to | |
273 | see the modes (permissions), timestamp, owner, group, and size, you can | |
274 | request that by also specifying the `\|\c | |
275 | .B v\c | |
276 | \|' modifier. | |
277 | ||
278 | If you do not specify any \c | |
279 | .I files\c | |
280 | \&, all files in the archive | |
281 | are listed. | |
282 | ||
283 | If there is more than one file with the same name (say, `\|\c | |
284 | .B fie\c | |
285 | \|') in | |
286 | an archive (say `\|\c | |
287 | .B b.a\c | |
288 | \|'), `\|\c | |
289 | .B ar t b.a fie\c | |
290 | \|' will list only the | |
291 | first instance; to see them all, you must ask for a complete | |
292 | listing\(em\&in our example, `\|\c | |
293 | .B ar t b.a\c | |
294 | \|'. | |
295 | ||
296 | .TP | |
297 | .B x | |
298 | \c | |
299 | .I Extract\c | |
300 | \& members (named \c | |
301 | .I files\c | |
302 | \&) from the archive. You can | |
303 | use the `\|\c | |
304 | .B v\c | |
305 | \|' modifier with this operation, to request that | |
306 | \c | |
307 | .B ar\c | |
308 | \& list each name as it extracts it. | |
309 | ||
310 | If you do not specify any \c | |
311 | .I files\c | |
312 | \&, all files in the archive | |
313 | are extracted. | |
314 | ||
315 | .PP | |
316 | ||
317 | A number of modifiers (\c | |
318 | .I mod\c | |
319 | \&) may immediately follow the \c | |
320 | .I p\c | |
321 | \& | |
322 | keyletter, to specify variations on an operation's behavior: | |
323 | ||
324 | .TP | |
325 | .B a | |
326 | Add new files \c | |
327 | .I after\c | |
328 | \& an existing member of the | |
329 | archive. If you use the modifier \c | |
330 | .B a\c | |
331 | \&, the name of an existing archive | |
332 | member must be present as the \c | |
333 | .I membername\c | |
334 | \& argument, before the | |
335 | \c | |
336 | .I archive\c | |
337 | \& specification. | |
338 | ||
339 | .TP | |
340 | .B b | |
341 | Add new files \c | |
342 | .I before\c | |
343 | \& an existing member of the | |
344 | archive. If you use the modifier \c | |
345 | .B b\c | |
346 | \&, the name of an existing archive | |
347 | member must be present as the \c | |
348 | .I membername\c | |
349 | \& argument, before the | |
350 | \c | |
351 | .I archive\c | |
352 | \& specification. (same as `\|\c | |
353 | .B i\c | |
354 | \|'). | |
355 | ||
356 | .TP | |
357 | .B c | |
358 | \c | |
359 | .I Create\c | |
360 | \& the archive. The specified \c | |
361 | .I archive\c | |
362 | \& is always | |
363 | created if it didn't exist, when you request an update. But a warning is | |
364 | issued unless you specify in advance that you expect to create it, by | |
365 | using this modifier. | |
366 | ||
367 | .TP | |
368 | .B i | |
369 | Insert new files \c | |
370 | .I before\c | |
371 | \& an existing member of the | |
372 | archive. If you use the modifier \c | |
373 | .B i\c | |
374 | \&, the name of an existing archive | |
375 | member must be present as the \c | |
376 | .I membername\c | |
377 | \& argument, before the | |
378 | \c | |
379 | .I archive\c | |
380 | \& specification. (same as `\|\c | |
381 | .B b\c | |
382 | \|'). | |
383 | ||
384 | .TP | |
385 | .B l | |
386 | This modifier is accepted but not used. | |
387 | ||
388 | .TP | |
389 | .B o | |
390 | Preserve the \c | |
391 | .I original\c | |
392 | \& dates of members when extracting them. If | |
393 | you do not specify this modifier, files extracted from the archive | |
394 | will be stamped with the time of extraction. | |
395 | ||
396 | .TP | |
397 | .B s | |
398 | Write an object-file index into the archive, or update an existing one, | |
399 | even if no other change is made to the archive. You may use this modifier | |
400 | flag either with any operation, or alone. Running `\|\c | |
401 | .B ar s\c | |
402 | \|' on an | |
403 | archive is equivalent to running `\|\c | |
404 | .B ranlib\c | |
405 | \|' on it. | |
406 | ||
407 | .TP | |
408 | .B u | |
409 | Normally, \c | |
410 | .B ar r\c | |
411 | \&.\|.\|. inserts all files | |
412 | listed into the archive. If you would like to insert \c | |
413 | .I only\c | |
414 | \& those | |
415 | of the files you list that are newer than existing members of the same | |
416 | names, use this modifier. The `\|\c | |
417 | .B u\c | |
418 | \|' modifier is allowed only for the | |
419 | operation `\|\c | |
420 | .B r\c | |
421 | \|' (replace). In particular, the combination `\|\c | |
422 | .B qu\c | |
423 | \|' is | |
424 | not allowed, since checking the timestamps would lose any speed | |
425 | advantage from the operation `\|\c | |
426 | .B q\c | |
427 | \|'. | |
428 | ||
429 | .TP | |
430 | .B v | |
431 | This modifier requests the \c | |
432 | .I verbose\c | |
433 | \& version of an operation. Many | |
434 | operations display additional information, such as filenames processed, | |
435 | when the modifier `\|\c | |
436 | .B v\c | |
437 | \|' is appended. | |
438 | ||
439 | .PP | |
440 | ||
441 | .SH "SEE ALSO" | |
442 | .RB "`\|" binutils "\|'" | |
443 | entry in | |
444 | .B | |
445 | info\c | |
446 | \&; | |
447 | .I | |
448 | The GNU Binary Utilities\c | |
449 | , Roland H. Pesch (October 1991). | |
450 | .BR nm ( 1 )\c | |
451 | \&, | |
452 | .BR ranlib( 1 )\c | |
453 | \&. | |
454 | ||
455 | .SH COPYING | |
456 | Copyright (c) 1991 Free Software Foundation, Inc. | |
457 | .PP | |
458 | Permission is granted to make and distribute verbatim copies of | |
459 | this manual provided the copyright notice and this permission notice | |
460 | are preserved on all copies. | |
461 | .PP | |
462 | Permission is granted to copy and distribute modified versions of this | |
463 | manual under the conditions for verbatim copying, provided that the | |
464 | entire resulting derived work is distributed under the terms of a | |
465 | permission notice identical to this one. | |
466 | .PP | |
467 | Permission is granted to copy and distribute translations of this | |
468 | manual into another language, under the above conditions for modified | |
469 | versions, except that this permission notice may be included in | |
470 | translations approved by the Free Software Foundation instead of in | |
471 | the original English. |