1 .\" Copyright (c) 1990, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" This code is derived from software contributed to Berkeley by
5 .\" Hugh Smith at The University of Guelph.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
17 .\" This product includes software developed by the University of
18 .\" California, Berkeley and its contributors.
19 .\" 4. Neither the name of the University nor the names of its contributors
20 .\" may be used to endorse or promote products derived from this software
21 .\" without specific prior written permission.
23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .\" @(#)ar.1 8.1 (Berkeley) 6/29/93
36 .\" $FreeBSD: src/usr.bin/ar/ar.1,v 1.6.2.8 2002/07/15 04:08:48 keramida Exp $
37 .\" $DragonFly: src/usr.bin/ar/Attic/ar.1,v 1.3 2006/02/17 19:38:54 swildner Exp $
44 .Nd create and maintain library archives
57 .Ar position archive Ar
73 .Ar position archive Ar
85 utility creates and maintains groups of files combined into an archive.
86 Once an archive has been created, new files can be added and existing
87 files can be extracted, deleted, or replaced.
89 Files are named in the archive by a single component, i.e., if a file
90 referenced by a path containing a slash (``/'') is archived it will be
91 named by the last component of that path.
92 When matching paths listed on the command line against file names stored
93 in the archive, only the last component of the path will be compared.
95 All informational and error messages use the path listed on the command
96 line, if any was specified; otherwise the name in the archive is used.
97 If multiple files in the archive have the same name, and paths are listed
98 on the command line to ``select'' archive files for an operation, only the
100 file with a matching name will be selected.
104 is for the creation and maintenance of libraries suitable for use with
107 although it is not restricted to this purpose.
109 The options are as follows:
110 .Bl -tag -width indent
112 A positioning modifier used with the options
116 The files are entered or moved
120 which must be specified.
122 A positioning modifier used with the options
126 The files are entered or moved
130 which must be specified.
132 Whenever an archive is created, an informational message to that effect
133 is written to standard error.
138 creates the archive silently.
140 Delete the specified archive files.
146 Move the specified archive files within the archive.
147 If one of the options
152 is specified, the files are moved
156 If none of those options are specified, the files are moved
157 to the end of the archive.
159 Set the access and modification times of extracted files to the
160 modification time of the file when it was entered into the archive.
161 This will fail if the user is not the owner of the extracted file
164 Write the contents of the specified archive files to the standard output.
165 If no files are specified, the contents of all the files in the archive
166 are written in the order they appear in the archive.
168 (Quickly) append the specified files to the archive.
169 If the archive does not exist a new archive file is created.
172 option, when creating a large archive
173 piece-by-piece, as no checking is done to see if the files already
174 exist in the archive.
176 Replace or add the specified files to the archive.
177 If the archive does not exist a new archive file is created.
178 Files that replace existing files do not change the order of the files
180 New files are appended to the archive unless one of the options
187 Select and/or name archive members using only the first fifteen characters
188 of the archive member or command line file name.
189 The historic archive format had sixteen bytes for the name, but some
190 historic archiver and loader implementations were unable to handle names
191 that used the entire space.
192 This means that file names that are not unique in their first fifteen
193 characters can subsequently be confused.
194 A warning message is printed to the standard error output if any file
198 for more information.)
200 List the specified files in the order in which they appear in the archive,
201 each on a separate line.
202 If no files are specified, all files in the archive are listed.
207 option, files in the archive will be replaced
208 only if the disk file has a newer modification time than the file in
212 option, files in the archive will be extracted
213 only if the archive file has a newer modification time than the file
216 Provide verbose output.
225 gives a file-by-file description of the archive modification.
226 This description consists of three, white-space separated fields: the
227 option letter, a dash (``-'') and the file name.
232 displays the description as above, but the initial letter is an ``a'' if
233 the file is added to the archive and an ``r'' if the file replaces a file
234 already in the archive.
239 the name of each printed file,
240 enclosed in less-than (``<'') and greater-than (``>'') characters,
241 is written to the standard output before
242 the contents of the file;
243 it is preceded by a single newline character, and
244 followed by two newline characters.
250 displays an ``ls -l'' style listing of information about the members of
252 This listing consists of eight, white-space separated fields:
253 the file permissions (see
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
258 format ``%b %e %H:%M %Y''), and the name of the file.
260 Extract the specified archive members into the files named by the command
262 If no members are specified, all the members of the archive are extracted into
263 the current directory.
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
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.
276 .Bl -tag -width indent -compact
278 The pathname of the directory to use when creating temporary files.
281 .Bl -tag -width indent -compact
283 default temporary file directory
292 writes archives that may be incompatible with historic archives, as
293 the format used for storing archive members with names longer than
294 fifteen characters has changed.
295 This implementation of
297 is backward compatible with previous versions of
299 in that it can read and write (using the
301 option) historic archives.
304 option is provided for compatibility only, and will be deleted
308 for more information.
317 utility is expected to offer a superset of the