1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
|
.\" Copyright (c) 2007 Joseph Koshy. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" This software is provided by Joseph Koshy ``as is'' and
.\" any express or implied warranties, including, but not limited to, the
.\" implied warranties of merchantability and fitness for a particular purpose
.\" are disclaimed. in no event shall Joseph Koshy be liable
.\" for any direct, indirect, incidental, special, exemplary, or consequential
.\" damages (including, but not limited to, procurement of substitute goods
.\" or services; loss of use, data, or profits; or business interruption)
.\" however caused and on any theory of liability, whether in contract, strict
.\" liability, or tort (including negligence or otherwise) arising in any way
.\" out of the use of this software, even if advised of the possibility of
.\" such damage.
.\"
.\" $FreeBSD$
.\"
.Dd August 31, 2007
.Os
.Dt AR 1
.Sh NAME
.Nm ar ,
.Nm ranlib
.Nd manage archives
.Sh SYNOPSIS
.Nm
.Fl d
.Op Fl T
.Op Fl j
.Op Fl v
.Op Fl z
.Ar archive
.Ar files ...
.Nm
.Fl m
.Op Fl T
.Op Fl a Ar position-after
.Op Fl b Ar position-before
.Op Fl i Ar position-before
.Op Fl j
.Op Fl s
.Op Fl z
.Ar archive
.Ar files ...
.Nm
.Fl p
.Op Fl T
.Op Fl v
.Ar archive
.Op Ar files ...
.Nm
.Fl r
.Op Fl T
.Op Fl a Ar position-after
.Op Fl b Ar position-before
.Op Fl c
.Op Fl i Ar position-before
.Op Fl j
.Op Fl s
.Op Fl u
.Op Fl v
.Op Fl z
.Ar archive
.Ar files ...
.Nm
.Fl s
.Op Fl j
.Op Fl z
.Ar archive
.Nm
.Fl t
.Op Fl T
.Op Fl v
.Ar archive
.Op Ar files ...
.Nm
.Fl x
.Op Fl C
.Op Fl T
.Op Fl o
.Op Fl u
.Op Fl v
.Ar archive
.Op Ar files ...
.Nm ranlib
.Ar archive ...
.Sh DESCRIPTION
The
.Nm
utility creates and maintains groups of files combined into an
archive.
Once an archive has been created, new files can be added to it, and
existing files can be extracted, deleted or replaced.
.Pp
Files are named in the archive by their last file name component,
so if a file referenced by a path containing a
.Dq /
is archived, it will be named by the last component of the path.
Similarly when matching paths listed on the command line against
file names stored in the archive, only the last component of the
path will be compared.
.Pp
The normal use of
.Nm
is for the creation and maintenance of libraries suitable for use
with the link editor
.Xr ld 1 ,
although it is not restricted to this purpose.
The
.Nm
utility can create and manage an archive symbol table (see
.Xr ar 5 )
used to speed up link editing operations.
If a symbol table is present in an archive, it will be
kept upto-date by subsequent operations on the archive (excepting
the quick update specified by the
.Fl q
option).
.Pp
The
.Nm ranlib
utility is used to add an archive symbol table
to an existing archive.
.Sh OPTIONS
The
.Nm
utility supports the following options:
.Bl -tag -width indent
.It Fl a Ar member-after
When used with option
.Fl m
this option specifies that the archive members specified by
arguments
.Ar files ...
are moved to after the archive member named by argument
.Ar member-after .
When used with option
.Fl r
this option specifies that the files specified by arguments
.Ar files ...
are added after the archive member named by argument
.Ar member-after .
.It Fl b Ar member-before
When used with option
.Fl m
this option specifies that the archive members specified by
arguments
.Ar files ...
are moved to before the archive member named by argument
.Ar member-before .
When used with option
.Fl r
this option specifies that the files specified by arguments
.Ar files ...
are added before the archive member named by argument
.Ar member-before .
.It Fl c
Suppress the informational message printed when a new archive is
created using the
.Fl r
and
.Fl q
options.
.It Fl C
Prevent extracted files from replacing like-named files
in the file system.
.It Fl d
Delete the members named by arguments
.Ar files ...
from the archive specified by argument
.Ar archive .
The archive's symbol table, if present, is updated to reflect
the new contents of the archive.
.It Fl f
Synonymous with option
.Fl T .
.It Fl i Ar member-before
Synonymous with option
.Fl b .
.It Fl j
Compress the resulting archive with
.Xr bzip2 1 .
.It Fl m
Move archive members specified by arguments
.Ar files ...
within the archive.
If a position has been specified by one of the
.Fl a ,
.Fl b
or
.Fl i
options, the members are moved to before or after the specified
position.
If no position has been specified, the specified members are moved
to the end of the archive.
If the archive has a symbol table, it is updated to reflect the
new contents of the archive.
.It Fl o
Preserve the original modification times of members when extracting
them.
.It Fl p
Write the contents of the specified archive members named by
arguments
.Ar files ...
to standard output.
If no members were specified, the contents of all the files in the
archive are written in the order they appear in the archive.
.It Fl q
Append the files specified by arguments
.Ar files ...
to the archive specified by argument
.Ar archive
without checking if the files already exist in the archive and
without updating the archive's symbol table.
If the archive file
.Ar archive
does not already exist, a new archive is created.
However, to be compatible with GNU
.Nm ,
.Fl q
is implemented as a synonym for
.Fl r .
.It Fl r
Replace (add) the files specified by arguments
.Ar files ...
in the archive specified by argument
.Ar archive ,
creating the archive if necessary.
Files that replace existing files do not change the order of files
within the archive.
If a file named in arguments
.Ar files ...
does not exist, existing members in the archive that match that
name are not changed.
New files are added to the end of the archive unless one of the
positioning options
.Fl a ,
.Fl b
or
.Fl i
is specified.
The archive symbol table, if it exists, is updated to reflect the
new state of the archive.
.It Fl s
Add an archive symbol table (see
.Xr ar 5 )
to the archive specified by argument
.Ar archive .
Invoking
.Nm
with the
.Fl s
option alone is equivalent to invoking
.Nm ranlib .
.It Fl t
List the files specified by arguments
.Ar files ...
in the order in which they appear in the archive, one per line.
If no files are specified, all files in the archive are listed.
.It Fl T
Use only the first fifteen characters of the archive member name or
command line file name argument when naming archive members.
.It Fl u
Conditionally update the archive or extract members.
When used with the
.Fl r
option, files named by arguments
.Ar files ...
will be replaced in the archive if they are newer than their
archived versions.
When used with the
.Fl x
option, the members specified by arguments
.Ar files ...
will be extracted only if they are newer than the corresponding
files in the file system.
.It Fl v
Provide verbose output.
When used with the
.Fl d ,
.Fl m ,
.Fl q
or
.Fl x
options,
.Nm
gives a file-by-file description of the archive modification being
performed, which consists of three white-space seperated fields:
the option letter, a dash
.Dq "-" ,
and the file name.
When used with the
.Fl r
option,
.Nm
displays the description as above, but the initial letter is an
.Dq a
if the file is added to the archive, or an
.Dq r
if the file replaces a file already in the archive.
When used with the
.Fl p
option, the name of the file enclosed in
.Dq <
and
.Dq >
characters is written to standard output preceded by a single newline
character and followed by two newline characters.
The contents of the named file follow the file name.
When used with the
.Fl t
option,
.Nm
displays eight whitespace separated fields:
the file permissions as displayed by
.Xr strmode 3 ,
decimal user and group IDs separated by a slash (
.Dq / Ns ) ,
the file size in bytes, the file modification time in
.Xr strftime 3
format
.Dq "%b %e %H:%M %Y" ,
and the name of the file.
.It Fl x
Extract archive members specified by arguments
.Ar files ...
into the current directory.
If no members have been specified, extract all members of the archive.
If the file corresponding to an extracted member does not exist it
will be created.
If the file corresponding to an extracted member does exist, its owner
and group will not be changed while its contents will be overwritten
and its permissions will set to that entered in the archive.
The file's access and modification time would be that of the time
of extraction unless the
.Fl o
option was specified.
.It Fl z
Compress the resulting archive with
.Xr gzip 1 .
.El
.Sh EXAMPLES
To create a new archive
.Pa ex.a
containing three files
.Pa ex1.o ,
.Pa ex2.o
and
.Pa ex3.o ,
use:
.Dl "ar -rc ex.a ex1.o ex2.o ex3.o"
.Pp
To add an archive symbol table to an existing archive
.Pa ex.a ,
use:
.Dl "ar -s ex.a"
.Pp
To delete file
.Pa ex1.o
from archive
.Pa ex.a ,
use:
.D1 "ar -d ex.a ex1.o"
.Pp
To verbosely list the contents of archive
.Pa ex.a ,
use:
.D1 "ar -tv ex.a"
.Sh DIAGNOSTICS
.Ex -std
.Sh SEE ALSO
.Xr ld 1 ,
.Xr archive 3 ,
.Xr elf 3 ,
.Xr strftime 3 ,
.Xr strmode 3 ,
.Xr ar 5
.\" .Sh COMPATIBILITY
.\" .Nm
.\" is expected to be compatible with GNU and SVR4
.\" .Nm .
.\" .Sh STANDARDS
.\" Do the POSIX/SuSv3 standards have anything to say about AR(1)?
.Sh HISTORY
An
.Nm
command first appeared in AT&T UNIX Version 1.
In
.Fx 8.0 ,
.An "Kai Wang" Aq kaiw@FreeBSD.org
reimplemented
.Nm
and
.Nm ranlib
using the
.Lb libarchive
and the
.Lb libelf .
|