Annotation of src/usr.bin/ar/ar.1, Revision 1.4
1.4 ! aaron 1: .\" $OpenBSD: ar.1,v 1.3 1997/08/19 07:23:13 denny Exp $
1.1 deraadt 2: .\" $NetBSD: ar.1,v 1.7 1995/08/18 15:05:11 pk Exp $
3: .\"
4: .\" Copyright (c) 1990, 1993
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" This code is derived from software contributed to Berkeley by
8: .\" Hugh Smith at The University of Guelph.
9: .\"
10: .\" Redistribution and use in source and binary forms, with or without
11: .\" modification, are permitted provided that the following conditions
12: .\" are met:
13: .\" 1. Redistributions of source code must retain the above copyright
14: .\" notice, this list of conditions and the following disclaimer.
15: .\" 2. Redistributions in binary form must reproduce the above copyright
16: .\" notice, this list of conditions and the following disclaimer in the
17: .\" documentation and/or other materials provided with the distribution.
18: .\" 3. All advertising materials mentioning features or use of this software
19: .\" must display the following acknowledgement:
20: .\" This product includes software developed by the University of
21: .\" California, Berkeley and its contributors.
22: .\" 4. Neither the name of the University nor the names of its contributors
23: .\" may be used to endorse or promote products derived from this software
24: .\" without specific prior written permission.
25: .\"
26: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
27: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
28: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
29: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
30: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
31: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
32: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
33: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
34: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
35: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36: .\" SUCH DAMAGE.
37: .\"
38: .\" @(#)ar.1 8.1 (Berkeley) 6/29/93
39: .\"
40: .Dd June 29, 1993
41: .Dt AR 1
42: .Os
43: .Sh NAME
44: .Nm ar
45: .Nd create and maintain library archives
46: .Sh SYNOPSIS
47: .Nm ar
48: .Fl d
49: .Op Fl \Tv
50: .Ar archive file ...
51: .Nm ar
52: .Fl m
53: .Op Fl \Tv
54: .Ar archive file ...
55: .Nm ar
56: .Fl m
57: .Op Fl abiTv
58: .Ar position archive file ...
59: .Nm ar
60: .Fl p
61: .Op Fl \Tv
62: .Ar archive
63: .Op Ar file ...
64: .Nm ar
65: .Fl q
66: .Op Fl cTv
67: .Ar archive file ...
68: .Nm ar
69: .Fl r
70: .Op Fl cuTv
71: .Ar archive file ...
72: .Nm ar
73: .Fl r
74: .Op Fl abciuTv
75: .Ar position archive file ...
76: .Nm ar
77: .Fl t
78: .Op Fl \Tv
79: .Ar archive
80: .Op Ar file ...
81: .Nm ar
82: .Fl x
1.3 denny 83: .Op Fl CouTv
1.1 deraadt 84: .Ar archive
85: .Op Ar file ...
86: .Sh DESCRIPTION
87: The
88: .Nm ar
89: utility creates and maintains groups of files combined into an archive.
90: Once an archive has been created, new files can be added and existing
91: files can be extracted, deleted, or replaced.
92: .Pp
93: Files are named in the archive by a single component, i.e., if a file
1.4 ! aaron 94: referenced by a path containing a slash (`/') is archived it will be
1.1 deraadt 95: named by the last component of that path.
96: When matching paths listed on the command line against file names stored
97: in the archive, only the last component of the path will be compared.
98: .Pp
99: All informational and error messages use the path listed on the command
100: line, if any was specified, otherwise the name in the archive is used.
101: If multiple files in the archive have the same name, and paths are listed
102: on the command line to ``select'' archive files for an operation, only the
103: .Em first
104: file with a matching name will be selected.
105: .Pp
106: The normal use of
107: .Nm ar
108: is for the creation and maintenance of libraries suitable for use with
109: the loader (see
110: .Xr ld 1 )
111: although it is not restricted to this purpose.
112: The options are as follows:
113: .Bl -tag -width indent
114: .It Fl a
115: A positioning modifier used with the options
116: .Fl r
117: and
118: .Fl m .
119: The files are entered or moved
120: .Em after
121: the archive member
122: .Ar position ,
123: which must be specified.
124: .It Fl b
125: A positioning modifier used with the options
126: .Fl r
127: and
128: .Fl m .
129: The files are entered or moved
130: .Em before
131: the archive member
132: .Ar position ,
133: which must be specified.
134: .It Fl c
135: Whenever an archive is created, an informational message to that effect
136: is written to standard error.
137: If the
138: .Fl c
139: option is specified,
140: .Nm ar
141: creates the archive silently.
1.3 denny 142: .It Fl C
143: Prevent extracted files from replacing like-named files in the file system.
1.1 deraadt 144: .It Fl d
145: Delete the specified archive files.
146: .It Fl i
147: Identical to the
148: .Fl b
149: option.
150: .It Fl m
151: Move the specified archive files within the archive.
152: If one of the options
153: .Fl a ,
154: .Fl b
155: or
156: .Fl i
157: are specified, the files are moved before or after the
158: .Ar position
159: file in the archive.
160: If none of those options are specified, the files are moved
161: to the end of the archive.
162: .It Fl o
163: Set the access and modification times of extracted files to the
164: modification time of the file when it was entered into the archive.
165: This will fail if the user is not the owner of the extracted file
166: or the super-user.
167: .It Fl p
168: Write the contents of the specified archive files to the standard output.
169: If no files are specified, the contents of all the files in the archive
170: are written in the order they appear in the archive.
171: .It Fl q
172: (Quickly) append the specified files to the archive.
173: If the archive does not exist a new archive file is created.
174: Much faster than the
175: .Fl r
176: option, when creating a large archive
177: piece-by-piece, as no checking is done to see if the files already
178: exist in the archive.
179: .It Fl r
180: Replace or add the specified files to the archive.
181: If the archive does not exist a new archive file is created.
182: Files that replace existing files do not change the order of the files
183: within the archive.
184: New files are appended to the archive unless one of the options
185: .Fl a ,
186: .Fl b
187: or
188: .Fl i
189: is specified.
190: .It Fl T
191: Select and/or name archive members using only the first fifteen characters
192: of the archive member or command line file name.
193: The historic archive format had sixteen bytes for the name, but some
194: historic archiver and loader implementations were unable to handle names
195: that used the entire space.
196: This means that file names that are not unique in their first fifteen
197: characters can subsequently be confused.
1.4 ! aaron 198: A warning message is printed to the standard error if any file
1.1 deraadt 199: names are truncated.
200: (See
201: .Xr ar 5
202: for more information.)
203: .It Fl t
204: List the specified files in the order in which they appear in the archive,
205: each on a separate line.
206: If no files are specified, all files in the archive are listed.
207: .It Fl u
208: Update files.
209: When used with the
210: .Fl r
211: option, files in the archive will be replaced
212: only if the disk file has a newer modification time than the file in
213: the archive.
214: When used with the
215: .Fl x
216: option, files in the archive will be extracted
217: only if the archive file has a newer modification time than the file
218: on disk.
219: .It Fl v
220: Provide verbose output.
221: When used with the
222: .Fl d ,
223: .Fl m ,
224: .Fl q
225: or
226: .Fl x
227: options,
228: .Nm ar
229: gives a file-by-file description of the archive modification.
230: This description consists of three, white-space separated fields: the
1.4 ! aaron 231: option letter, a dash (`-') and the file name.
1.1 deraadt 232: When used with the
233: .Fl r
234: option,
235: .Nm ar
236: displays the description as above, but the initial letter is an ``a'' if
237: the file is added to the archive and an ``r'' if the file replaces a file
238: already in the archive.
239: .Pp
240: When used with the
241: .Fl p
242: option,
243: the name of each printed file is written to the standard output before
244: the contents of the file, preceded by a single newline character, and
1.4 ! aaron 245: followed by two newline characters, enclosed in less-than (`<') and
! 246: greater-than (`>') characters.
1.1 deraadt 247: .Pp
248: When used with the
249: .Fl t
250: option,
251: .Nm ar
252: displays an ``ls -l'' style listing of information about the members of
253: the archive.
254: This listing consists of eight, white-space separated fields:
255: the file permissions (see
256: .Xr strmode 3 ),
1.4 ! aaron 257: the decimal user and group ID's, separated by a single slash (`/'),
1.1 deraadt 258: the file size (in bytes), the file modification time (in the
259: .Xr date 1
260: format ``%b %e %H:%M %Y''), and the name of the file.
261: .It Fl x
262: Extract the specified archive members into the files named by the command
263: line arguments.
264: If no members are specified, all the members of the archive are extracted into
265: the current directory.
266: .Pp
267: If the file does not exist, it is created; if it does exist, the owner
268: and group will be unchanged.
269: The file access and modification times are the time of the extraction
270: (but see the
271: .Fl o
272: option).
273: The file permissions will be set to those of the file when it was entered
274: into the archive; this will fail if the user is not the owner of the
275: extracted file or the super-user.
276: .El
277: .Pp
278: The
279: .Nm ar
1.4 ! aaron 280: utility exits 0 on success or >0 if an error occurred.
1.1 deraadt 281: .Sh ENVIRONMENT
282: .Bl -tag -width indent -compact
283: .It Ev TMPDIR
284: The pathname of the directory to use when creating temporary files.
285: .El
286: .Sh FILES
1.4 ! aaron 287: .Bl -tag -width ar.XXXXXX -compact
1.1 deraadt 288: .It Pa /tmp
289: default temporary file directory
290: .It Pa ar.XXXXXX
291: temporary file names
292: .El
293: .Sh COMPATIBILITY
294: By default,
295: .Nm ar
296: writes archives that may be incompatible with historic archives, as
297: the format used for storing archive members with names longer than
298: fifteen characters has changed.
299: This implementation of
300: .Nm ar
301: is backward compatible with previous versions of
302: .Nm ar
303: in that it can read and write (using the
304: .Fl T
305: option) historic archives.
306: The
307: .Fl T
308: option is provided for compatibility only, and will be deleted
309: in a future release.
310: See
311: .Xr ar 5
312: for more information.
313: .Sh STANDARDS
314: The
315: .Nm ar
316: utility is expected to offer a superset of the
317: .St -p1003.2
318: functionality.
319: .Sh SEE ALSO
320: .Xr ld 1 ,
321: .Xr ranlib 1 ,
322: .Xr strmode 3 ,
323: .Xr ar 5