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