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