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