Annotation of src/usr.bin/ar/ar.1, Revision 1.6
1.6 ! fgsch 1: .\" $OpenBSD: ar.1,v 1.5 1999/06/05 01:21:17 aaron 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
1.5 aaron 41: .Dt AR 1
1.1 deraadt 42: .Os
43: .Sh NAME
1.5 aaron 44: .Nm ar
1.1 deraadt 45: .Nd create and maintain library archives
46: .Sh SYNOPSIS
47: .Nm ar
1.5 aaron 48: .Fl d
49: .Op Fl \Tv
1.1 deraadt 50: .Ar archive file ...
51: .Nm ar
52: .Fl m
1.5 aaron 53: .Op Fl \Tv
1.1 deraadt 54: .Ar archive file ...
55: .Nm ar
56: .Fl m
1.5 aaron 57: .Op Fl abiTv
1.1 deraadt 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
1.5 aaron 88: .Nm
1.1 deraadt 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.5 aaron 94: referenced by a path containing a slash
95: .Pq Ql /
96: is archived it will be
1.1 deraadt 97: named by the last component of that path.
98: When matching paths listed on the command line against file names stored
99: in the archive, only the last component of the path will be compared.
100: .Pp
101: All informational and error messages use the path listed on the command
102: line, if any was specified, otherwise the name in the archive is used.
103: If multiple files in the archive have the same name, and paths are listed
1.5 aaron 104: on the command line to
105: .Dq select
106: archive files for an operation, only the
1.1 deraadt 107: .Em first
108: file with a matching name will be selected.
109: .Pp
110: The normal use of
1.5 aaron 111: .Nm
1.1 deraadt 112: is for the creation and maintenance of libraries suitable for use with
113: the loader (see
114: .Xr ld 1 )
115: although it is not restricted to this purpose.
116: The options are as follows:
117: .Bl -tag -width indent
118: .It Fl a
1.5 aaron 119: A positioning modifier used with the options
120: .Fl r
121: and
1.1 deraadt 122: .Fl m .
123: The files are entered or moved
124: .Em after
125: the archive member
126: .Ar position ,
127: which must be specified.
128: .It Fl b
129: A positioning modifier used with the options
1.5 aaron 130: .Fl r
131: and
1.1 deraadt 132: .Fl m .
133: The files are entered or moved
134: .Em before
135: the archive member
136: .Ar position ,
137: which must be specified.
138: .It Fl c
139: Whenever an archive is created, an informational message to that effect
140: is written to standard error.
1.5 aaron 141: If the
1.1 deraadt 142: .Fl c
143: option is specified,
1.5 aaron 144: .Nm
1.1 deraadt 145: creates the archive silently.
1.3 denny 146: .It Fl C
147: Prevent extracted files from replacing like-named files in the file system.
1.1 deraadt 148: .It Fl d
149: Delete the specified archive files.
150: .It Fl i
1.5 aaron 151: Identical to the
1.1 deraadt 152: .Fl b
153: option.
154: .It Fl m
155: Move the specified archive files within the archive.
1.5 aaron 156: If one of the options
157: .Fl a ,
158: .Fl b
159: or
1.1 deraadt 160: .Fl i
161: are specified, the files are moved before or after the
162: .Ar position
163: file in the archive.
164: If none of those options are specified, the files are moved
165: to the end of the archive.
166: .It Fl o
167: Set the access and modification times of extracted files to the
168: modification time of the file when it was entered into the archive.
169: This will fail if the user is not the owner of the extracted file
170: or the super-user.
171: .It Fl p
172: Write the contents of the specified archive files to the standard output.
173: If no files are specified, the contents of all the files in the archive
174: are written in the order they appear in the archive.
175: .It Fl q
176: (Quickly) append the specified files to the archive.
177: If the archive does not exist a new archive file is created.
1.5 aaron 178: Much faster than the
1.1 deraadt 179: .Fl r
180: option, when creating a large archive
181: piece-by-piece, as no checking is done to see if the files already
182: exist in the archive.
183: .It Fl r
184: Replace or add the specified files to the archive.
185: If the archive does not exist a new archive file is created.
186: Files that replace existing files do not change the order of the files
187: within the archive.
1.5 aaron 188: New files are appended to the archive unless one of the options
1.1 deraadt 189: .Fl a ,
190: .Fl b
1.5 aaron 191: or
1.1 deraadt 192: .Fl i
193: is specified.
194: .It Fl T
195: Select and/or name archive members using only the first fifteen characters
196: of the archive member or command line file name.
197: The historic archive format had sixteen bytes for the name, but some
198: historic archiver and loader implementations were unable to handle names
199: that used the entire space.
200: This means that file names that are not unique in their first fifteen
201: characters can subsequently be confused.
1.4 aaron 202: A warning message is printed to the standard error if any file
1.1 deraadt 203: names are truncated.
204: (See
205: .Xr ar 5
206: for more information.)
207: .It Fl t
208: List the specified files in the order in which they appear in the archive,
209: each on a separate line.
210: If no files are specified, all files in the archive are listed.
211: .It Fl u
212: Update files.
1.5 aaron 213: When used with the
1.1 deraadt 214: .Fl r
215: option, files in the archive will be replaced
216: only if the disk file has a newer modification time than the file in
217: the archive.
1.5 aaron 218: When used with the
1.1 deraadt 219: .Fl x
220: option, files in the archive will be extracted
221: only if the archive file has a newer modification time than the file
222: on disk.
223: .It Fl v
224: Provide verbose output.
1.5 aaron 225: When used with the
226: .Fl d ,
227: .Fl m ,
228: .Fl q
229: or
1.1 deraadt 230: .Fl x
231: options,
1.5 aaron 232: .Nm
1.1 deraadt 233: gives a file-by-file description of the archive modification.
234: This description consists of three, white-space separated fields: the
1.5 aaron 235: option letter, a dash
236: .Pq Ql -
237: and the file name.
238: When used with the
1.1 deraadt 239: .Fl r
240: option,
1.5 aaron 241: .Nm
242: displays the description as above, but the initial letter is an
243: .Sq a
244: if
245: the file is added to the archive and an
246: .Sq r
247: if the file replaces a file
1.1 deraadt 248: already in the archive.
249: .Pp
1.5 aaron 250: When used with the
251: .Fl p
1.1 deraadt 252: option,
253: the name of each printed file is written to the standard output before
254: the contents of the file, preceded by a single newline character, and
1.5 aaron 255: followed by two newline characters, enclosed in less-than
256: .Pq Ql <
257: and
258: greater-than
259: .Pq Ql >
260: characters.
1.1 deraadt 261: .Pp
1.5 aaron 262: When used with the
1.1 deraadt 263: .Fl t
264: option,
1.5 aaron 265: .Nm
266: displays an
267: .Dq ls -l
268: style listing of information about the members of
1.1 deraadt 269: the archive.
270: This listing consists of eight, white-space separated fields:
271: the file permissions (see
272: .Xr strmode 3 ),
1.5 aaron 273: the decimal user and group IDs, separated by a single slash
274: .Pq Ql / ,
1.1 deraadt 275: the file size (in bytes), the file modification time (in the
276: .Xr date 1
1.5 aaron 277: format
278: .Dq %b %e %H:%M %Y ) ,
279: and the name of the file.
1.1 deraadt 280: .It Fl x
281: Extract the specified archive members into the files named by the command
282: line arguments.
283: If no members are specified, all the members of the archive are extracted into
284: the current directory.
285: .Pp
286: If the file does not exist, it is created; if it does exist, the owner
287: and group will be unchanged.
288: The file access and modification times are the time of the extraction
1.5 aaron 289: (but see the
1.1 deraadt 290: .Fl o
291: option).
292: The file permissions will be set to those of the file when it was entered
293: into the archive; this will fail if the user is not the owner of the
294: extracted file or the super-user.
295: .El
296: .Pp
297: The
1.5 aaron 298: .Nm
1.4 aaron 299: utility exits 0 on success or >0 if an error occurred.
1.1 deraadt 300: .Sh ENVIRONMENT
301: .Bl -tag -width indent -compact
302: .It Ev TMPDIR
303: The pathname of the directory to use when creating temporary files.
304: .El
305: .Sh FILES
1.6 ! fgsch 306: .Bl -tag -width ar.XXXXXXXXXX -compact
1.1 deraadt 307: .It Pa /tmp
308: default temporary file directory
1.6 ! fgsch 309: .It Pa ar.XXXXXXXXXX
1.1 deraadt 310: temporary file names
311: .El
312: .Sh COMPATIBILITY
313: By default,
1.5 aaron 314: .Nm
1.1 deraadt 315: writes archives that may be incompatible with historic archives, as
316: the format used for storing archive members with names longer than
317: fifteen characters has changed.
318: This implementation of
1.5 aaron 319: .Nm
1.1 deraadt 320: is backward compatible with previous versions of
1.5 aaron 321: .Nm
322: in that it can read and write (using the
1.1 deraadt 323: .Fl T
324: option) historic archives.
1.5 aaron 325: The
1.1 deraadt 326: .Fl T
327: option is provided for compatibility only, and will be deleted
328: in a future release.
329: See
330: .Xr ar 5
331: for more information.
332: .Sh STANDARDS
333: The
1.5 aaron 334: .Nm
335: utility is expected to offer a superset of the
1.1 deraadt 336: .St -p1003.2
337: functionality.
338: .Sh SEE ALSO
1.5 aaron 339: .Xr ld 1 ,
1.1 deraadt 340: .Xr ranlib 1 ,
341: .Xr strmode 3 ,
342: .Xr ar 5
![[BACK]](/icons/back.gif){kind=icon}
Return to ar.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / ar