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