xref: /freebsd/usr.bin/ar/ar.1 (revision bb15ca603fa442c72dde3f3cb8b46db6970e3950)
1.\" Copyright (c) 2007 Joseph Koshy.  All rights reserved.
2.\"
3.\" Redistribution and use in source and binary forms, with or without
4.\" modification, are permitted provided that the following conditions
5.\" are met:
6.\" 1. Redistributions of source code must retain the above copyright
7.\"    notice, this list of conditions and the following disclaimer.
8.\" 2. Redistributions in binary form must reproduce the above copyright
9.\"    notice, this list of conditions and the following disclaimer in the
10.\"    documentation and/or other materials provided with the distribution.
11.\"
12.\" This software is provided by Joseph Koshy ``as is'' and
13.\" any express or implied warranties, including, but not limited to, the
14.\" implied warranties of merchantability and fitness for a particular purpose
15.\" are disclaimed.  in no event shall Joseph Koshy be liable
16.\" for any direct, indirect, incidental, special, exemplary, or consequential
17.\" damages (including, but not limited to, procurement of substitute goods
18.\" or services; loss of use, data, or profits; or business interruption)
19.\" however caused and on any theory of liability, whether in contract, strict
20.\" liability, or tort (including negligence or otherwise) arising in any way
21.\" out of the use of this software, even if advised of the possibility of
22.\" such damage.
23.\"
24.\" $FreeBSD$
25.\"
26.Dd May 17, 2010
27.Dt AR 1
28.Os
29.Sh NAME
30.Nm ar ,
31.Nm ranlib
32.Nd manage archives
33.Sh SYNOPSIS
34.Nm
35.Fl d
36.Op Fl T
37.Op Fl f
38.Op Fl j
39.Op Fl v
40.Op Fl z
41.Ar archive
42.Ar
43.Nm
44.Fl m
45.Op Fl T
46.Op Fl a Ar position-after
47.Op Fl b Ar position-before
48.Op Fl f
49.Op Fl i Ar position-before
50.Op Fl j
51.Op Fl s | Fl S
52.Op Fl z
53.Ar archive
54.Ar
55.Nm
56.Fl p
57.Op Fl T
58.Op Fl f
59.Op Fl v
60.Ar archive
61.Op Ar
62.Nm
63.Fl q
64.Op Fl T
65.Op Fl c
66.Op Fl D
67.Op Fl f
68.Op Fl s | Fl S
69.Op Fl v
70.Op Fl z
71.Ar archive
72.Ar
73.Nm
74.Fl r
75.Op Fl T
76.Op Fl a Ar position-after
77.Op Fl b Ar position-before
78.Op Fl c
79.Op Fl D
80.Op Fl f
81.Op Fl i Ar position-before
82.Op Fl j
83.Op Fl s | Fl S
84.Op Fl u
85.Op Fl v
86.Op Fl z
87.Ar archive
88.Ar
89.Nm
90.Fl s
91.Op Fl j
92.Op Fl z
93.Ar archive
94.Nm
95.Fl t
96.Op Fl f
97.Op Fl T
98.Op Fl v
99.Ar archive
100.Op Ar
101.Nm
102.Fl x
103.Op Fl C
104.Op Fl T
105.Op Fl f
106.Op Fl o
107.Op Fl u
108.Op Fl v
109.Ar archive
110.Op Ar
111.Nm
112.Fl M
113.Nm ranlib
114.Op Fl D
115.Ar archive ...
116.Sh DESCRIPTION
117The
118.Nm
119utility creates and maintains groups of files combined into an
120archive.
121Once an archive has been created, new files can be added to it, and
122existing files can be extracted, deleted or replaced.
123.Pp
124Files are named in the archive by their last file name component,
125so if a file referenced by a path containing a
126.Dq /
127is archived, it will be named by the last component of the path.
128Similarly when matching paths listed on the command line against
129file names stored in the archive, only the last component of the
130path will be compared.
131.Pp
132The normal use of
133.Nm
134is for the creation and maintenance of libraries suitable for use
135with the link editor
136.Xr ld 1 ,
137although it is not restricted to this purpose.
138The
139.Nm
140utility can create and manage an archive symbol table (see
141.Xr ar 5 )
142used to speed up link editing operations.
143If a symbol table is present in an archive, it will be
144kept up-to-date by subsequent operations on the archive.
145.Pp
146The
147.Nm ranlib
148utility is used to add an archive symbol table
149to an existing archive.
150.Sh OPTIONS
151The
152.Nm
153utility supports the following options:
154.Bl -tag -width indent
155.It Fl a Ar member-after
156When used with option
157.Fl m
158this option specifies that the archive members specified by
159arguments
160.Ar
161are moved to after the archive member named by argument
162.Ar member-after .
163When used with option
164.Fl r
165this option specifies that the files specified by arguments
166.Ar
167are added after the archive member named by argument
168.Ar member-after .
169.It Fl b Ar member-before
170When used with option
171.Fl m
172this option specifies that the archive members specified by
173arguments
174.Ar
175are moved to before the archive member named by argument
176.Ar member-before .
177When used with option
178.Fl r
179this option specifies that the files specified by arguments
180.Ar
181are added before the archive member named by argument
182.Ar member-before .
183.It Fl c
184Suppress the informational message printed when a new archive is
185created using the
186.Fl r
187and
188.Fl q
189options.
190.It Fl C
191Prevent extracted files from replacing like-named files
192in the file system.
193.It Fl d
194Delete the members named by arguments
195.Ar
196from the archive specified by argument
197.Ar archive .
198The archive's symbol table, if present, is updated to reflect
199the new contents of the archive.
200.It Fl D
201When used in combination with the
202.Fl r
203or
204.Fl q
205option, insert 0's instead of the real mtime, uid and gid values
206and 0644 instead of file mode from the members named by arguments
207.Ar .
208This ensures that checksums on the resulting archives are reproducible
209when member contents are identical.
210.It Fl f
211Synonymous with option
212.Fl T .
213.It Fl i Ar member-before
214Synonymous with option
215.Fl b .
216.It Fl j
217This option is accepted but ignored.
218.It Fl l
219This option is accepted for compatibility with GNU
220.Xr ar 1 ,
221but is ignored.
222.It Fl m
223Move archive members specified by arguments
224.Ar
225within the archive.
226If a position has been specified by one of the
227.Fl a ,
228.Fl b
229or
230.Fl i
231options, the members are moved to before or after the specified
232position.
233If no position has been specified, the specified members are moved
234to the end of the archive.
235If the archive has a symbol table, it is updated to reflect the
236new contents of the archive.
237.It Fl M
238Read and execute MRI librarian commands from standard input.
239The commands understood by the
240.Nm
241utility are described in the section
242.Sx "MRI Librarian Commands" .
243.It Fl o
244Preserve the original modification times of members when extracting
245them.
246.It Fl p
247Write the contents of the specified archive members named by
248arguments
249.Ar
250to standard output.
251If no members were specified, the contents of all the files in the
252archive are written in the order they appear in the archive.
253.It Fl q
254Append the files specified by arguments
255.Ar
256to the archive specified by argument
257.Ar archive
258without checking if the files already exist in the archive.
259The archive symbol table will be updated as needed.
260If the file specified by the argument
261.Ar archive
262does not already exist, a new archive will be created.
263.It Fl r
264Replace (add) the files specified by arguments
265.Ar
266in the archive specified by argument
267.Ar archive ,
268creating the archive if necessary.
269Replacing existing members will not change the order of members within
270the archive.
271If a file named in arguments
272.Ar
273does not exist, existing members in the archive that match that
274name are not changed.
275New files are added to the end of the archive unless one of the
276positioning options
277.Fl a ,
278.Fl b
279or
280.Fl i
281is specified.
282The archive symbol table, if it exists, is updated to reflect the
283new state of the archive.
284.It Fl s
285Add an archive symbol table (see
286.Xr ar 5 )
287to the archive specified by argument
288.Ar archive .
289Invoking
290.Nm
291with the
292.Fl s
293option alone is equivalent to invoking
294.Nm ranlib .
295.It Fl S
296Do not generate an archive symbol table.
297.It Fl t
298List the files specified by arguments
299.Ar
300in the order in which they appear in the archive, one per line.
301If no files are specified, all files in the archive are listed.
302.It Fl T
303Use only the first fifteen characters of the archive member name or
304command line file name argument when naming archive members.
305.It Fl u
306Conditionally update the archive or extract members.
307When used with the
308.Fl r
309option, files named by arguments
310.Ar
311will be replaced in the archive if they are newer than their
312archived versions.
313When used with the
314.Fl x
315option, the members specified by arguments
316.Ar
317will be extracted only if they are newer than the corresponding
318files in the file system.
319.It Fl v
320Provide verbose output.
321When used with the
322.Fl d ,
323.Fl m ,
324.Fl q
325or
326.Fl x
327options,
328.Nm
329gives a file-by-file description of the archive modification being
330performed, which consists of three white-space separated fields:
331the option letter, a dash
332.Dq "-" ,
333and the file name.
334When used with the
335.Fl r
336option,
337.Nm
338displays the description as above, but the initial letter is an
339.Dq a
340if the file is added to the archive, or an
341.Dq r
342if the file replaces a file already in the archive.
343When used with the
344.Fl p
345option, the name of the file enclosed in
346.Dq <
347and
348.Dq >
349characters is written to standard output preceded by a single newline
350character and followed by two newline characters.
351The contents of the named file follow the file name.
352When used with the
353.Fl t
354option,
355.Nm
356displays eight whitespace separated fields:
357the file permissions as displayed by
358.Xr strmode 3 ,
359decimal user and group IDs separated by a slash (
360.Dq / Ns ) ,
361the file size in bytes, the file modification time in
362.Xr strftime 3
363format
364.Dq "%b %e %H:%M %Y" ,
365and the name of the file.
366.It Fl V
367Print a version string and exit.
368.It Fl x
369Extract archive members specified by arguments
370.Ar
371into the current directory.
372If no members have been specified, extract all members of the archive.
373If the file corresponding to an extracted member does not exist it
374will be created.
375If the file corresponding to an extracted member does exist, its owner
376and group will not be changed while its contents will be overwritten
377and its permissions will set to that entered in the archive.
378The file's access and modification time would be that of the time
379of extraction unless the
380.Fl o
381option was specified.
382.It Fl z
383This option is accepted but ignored.
384.El
385.Ss "MRI Librarian Commands"
386If the
387.Fl M
388option is specified, the
389.Nm
390utility will read and execute commands from its standard input.
391If standard input is a terminal, the
392.Nm
393utility will display the prompt
394.Dq Li "AR >"
395before reading a line, and will continue operation even if errors are
396encountered.
397If standard input is not a terminal, the
398.Nm
399utility will not display a prompt and will terminate execution on
400encountering an error.
401.Pp
402Each input line contains a single command.
403Words in an input line are separated by whitespace characters.
404The first word of the line is the command, the remaining words are
405the arguments to the command.
406The command word may be specified in either case.
407Arguments may be separated by commas or blanks.
408.Pp
409Empty lines are allowed and are ignored.
410Long lines are continued by ending them with the
411.Dq Li +
412character.
413.Pp
414The
415.Dq Li *
416and
417.Dq Li "\;"
418characters start a comment.
419Comments extend till the end of the line.
420.Pp
421When executing an MRI librarian script the
422.Nm
423utility works on a temporary copy of an archive.
424Changes to the copy are made permanent using the
425.Ic save
426command.
427.Pp
428Commands understood by the
429.Nm
430utility are:
431.Bl -tag -width indent
432.It Ic addlib Ar archive | Ic addlib Ar archive Pq Ar member Oo Li , Ar member Oc Ns ...
433Add the contents of the archive named by argument
434.Ar archive
435to the current archive.
436If specific members are named using the arguments
437.Ar member ,
438then those members are added to the current archive.
439If no members are specified, the entire contents of the archive
440are added to the current archive.
441.It Ic addmod Ar member Oo Li , Ar member Oc Ns ...
442Add the files named by arguments
443.Ar member
444to the current archive.
445.It Ic clear
446Discard all the contents of the current archive.
447.It Ic create Ar archive
448Create a new archive named by the argument
449.Ar archive ,
450and makes it the current archive.
451If the named archive already exists, it will be overwritten
452when the
453.Ic save
454command is issued.
455.It Ic delete Ar module Oo Li , Ar member Oc Ns ...
456Delete the modules named by the arguments
457.Ar member
458from the current archive.
459.It Ic directory Ar archive Po Ar member Oo Li , Ar member Oc Ns ... Pc Op Ar outputfile
460List each named module in the archive.
461The format of the output depends on the verbosity setting set using
462the
463.Ic verbose
464command.
465Output is sent to standard output, or to the file specified by
466argument
467.Ar outputfile .
468.It Ic end
469Exit successfully from the
470.Nm
471utility.
472Any unsaved changes to the current archive will be discarded.
473.It Ic extract Ar member Oo Li , Ar member Oc Ns ...
474Extract the members named by the arguments
475.Ar member
476from the current archive.
477.It Ic list
478Display the contents of the current archive in verbose style.
479.It Ic open Ar archive
480Open the archive named by argument
481.Ar archive
482and make it the current archive.
483.It Ic replace Ar member Oo Li , Ar member Oc Ns ...
484Replace named members in the current archive with the files specified
485by arguments
486.Ar member .
487The files must be present in the current directory and the named
488modules must already exist in the current archive.
489.It Ic save
490Commit all changes to the current archive.
491.It Ic verbose
492Toggle the verbosity of the
493.Ic directory
494command.
495.El
496.Sh EXAMPLES
497To create a new archive
498.Pa ex.a
499containing three files
500.Pa ex1.o ,
501.Pa ex2.o
502and
503.Pa ex3.o ,
504use:
505.Dl "ar -rc ex.a ex1.o ex2.o ex3.o"
506.Pp
507To add an archive symbol table to an existing archive
508.Pa ex.a ,
509use:
510.Dl "ar -s ex.a"
511.Pp
512To delete file
513.Pa ex1.o
514from archive
515.Pa ex.a ,
516use:
517.D1 "ar -d ex.a ex1.o"
518.Pp
519To verbosely list the contents of archive
520.Pa ex.a ,
521use:
522.D1 "ar -tv ex.a"
523.Pp
524To create a new archive
525.Pa ex.a
526containing the files
527.Pa ex1.o ,
528and
529.Pa ex2.o ,
530using MRI librarian commands, use the following script:
531.Bd -literal -offset indent
532create ex.a		 * specify the output archive
533addmod ex1.o ex2.o	 * add modules
534save			 * save pending changes
535end			 * exit the utility
536.Ed
537.Sh DIAGNOSTICS
538.Ex -std
539.Sh SEE ALSO
540.Xr ld 1 ,
541.Xr archive 3 ,
542.Xr elf 3 ,
543.Xr strftime 3 ,
544.Xr strmode 3 ,
545.Xr ar 5
546.Sh STANDARDS COMPLIANCE
547The
548.Nm
549utility's support for the
550.Fl a ,
551.Fl b ,
552.Fl c ,
553.Fl i ,
554.Fl m ,
555.Fl p ,
556.Fl q ,
557.Fl r ,
558.Fl s ,
559.Fl t ,
560.Fl u ,
561.Fl v ,
562.Fl C
563and
564.Fl T
565options is believed to be compliant with
566.St -p1003.2 .
567.Sh HISTORY
568An
569.Nm
570command first appeared in AT&T UNIX Version 1.
571In
572.Fx 8.0 ,
573.An "Kai Wang" Aq kaiw@FreeBSD.org
574reimplemented
575.Nm
576and
577.Nm ranlib
578using the
579.Lb libarchive
580and the
581.Lb libelf .
582