Commit | Line | Data |
---|---|---|
15637ed4 RG |
1 | .\" Copyright (c) 1990 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" This code is derived from software contributed to Berkeley by | |
5 | .\" Hugh Smith at The University of Guelph. | |
6 | .\" | |
7 | .\" Redistribution and use in source and binary forms, with or without | |
8 | .\" modification, are permitted provided that the following conditions | |
9 | .\" are met: | |
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. | |
22 | .\" | |
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 | |
33 | .\" SUCH DAMAGE. | |
34 | .\" | |
35 | .\" @(#)ar.1 6.10 (Berkeley) 3/21/91 | |
36 | .\" | |
37 | .TH AR 1 "March 21, 1991" | |
38 | .AT 3 | |
39 | .SH NAME | |
40 | ar \- create and maintain library archives | |
41 | .SH SYNOPSIS | |
42 | .nf | |
43 | .ft B | |
44 | ar -d [-Tv] archive file ... | |
45 | ar -m [-Tv] archive file ... | |
46 | ar -m [-abiTv] position archive file ... | |
47 | ar -p [-Tv] archive [file ...] | |
48 | ar -q [-cTv] archive file ... | |
49 | ar -r [-cuTv] archive file ... | |
50 | ar -r [-abciuTv] position archive file ... | |
51 | ar -t [-Tv] archive [file ...] | |
52 | ar -x [-ouTv] archive [file ...] | |
53 | .fi | |
54 | .ft R | |
55 | .SH DESCRIPTION | |
56 | The | |
57 | .I ar | |
58 | utility creates and maintains groups of files combined into an archive. | |
59 | Once an archive has been created, new files can be added and existing | |
60 | files can be extracted, deleted, or replaced. | |
61 | .PP | |
62 | Files are named in the archive by a single component, i.e., if a file | |
63 | referenced by a path containing a slash (``/'') is archived it will be | |
64 | named by the last component of that path. | |
65 | When matching paths listed on the command line against file names stored | |
66 | in the archive, only the last component of the path will be compared. | |
67 | .PP | |
68 | All informational and error messages use the path listed on the command | |
69 | line, if any was specified, otherwise the name in the archive is used. | |
70 | If multiple files in the archive have the same name, and paths are listed | |
71 | on the command line to ``select'' archive files for an operation, only the | |
72 | .B first | |
73 | file with a matching name will be selected. | |
74 | .PP | |
75 | The normal use of | |
76 | .I ar | |
77 | is for the creation and maintenance of libraries suitable for use with | |
78 | the loader (see | |
79 | .IR ld (1)) | |
80 | although it is not restricted to this purpose. | |
81 | The options are as follows: | |
82 | .TP | |
83 | \-a | |
84 | A positioning modifier used with the options \-r and \-m. | |
85 | The files are entered or moved | |
86 | .B after | |
87 | the archive member | |
88 | .IR position , | |
89 | which must be specified. | |
90 | .TP | |
91 | \-b | |
92 | A positioning modifier used with the options \-r and \-m. | |
93 | The files are entered or moved | |
94 | .B before | |
95 | the archive member | |
96 | .IR position , | |
97 | which must be specified. | |
98 | .TP | |
99 | \-c | |
100 | Whenever an archive is created, an informational message to that effect | |
101 | is written to standard error. | |
102 | If the \-c option is specified, | |
103 | .I ar | |
104 | creates the archive silently. | |
105 | .TP | |
106 | \-d | |
107 | Delete the specified archive files. | |
108 | .TP | |
109 | \-i | |
110 | Identical to the \-b option. | |
111 | .TP | |
112 | \-m | |
113 | Move the specified archive files within the archive. | |
114 | If one of the options \-a, \-b or \-i are specified, the files are moved | |
115 | before or after the | |
116 | .I position | |
117 | file in the archive. | |
118 | If none of those options are specified, the files are moved | |
119 | to the end of the archive. | |
120 | .TP | |
121 | \-o | |
122 | Set the access and modification times of extracted files to the | |
123 | modification time of the file when it was entered into the archive. | |
124 | This will fail if the user is not the owner of the extracted file | |
125 | or the super-user. | |
126 | .TP | |
127 | \-p | |
128 | Write the contents of the specified archive files to the standard output. | |
129 | If no files are specified, the contents of all the files in the archive | |
130 | are written in the order they appear in the archive. | |
131 | .TP | |
132 | \-q | |
133 | (Quickly) append the specified files to the archive. | |
134 | If the archive does not exist a new archive file is created. | |
135 | Much faster than the \-r option, when creating a large archive | |
136 | piece-by-piece, as no checking is done to see if the files already | |
137 | exist in the archive. | |
138 | .TP | |
139 | \-r | |
140 | Replace or add the specified files to the archive. | |
141 | If the archive does not exist a new archive file is created. | |
142 | Files that replace existing files do not change the order of the files | |
143 | within the archive. | |
144 | New files are appended to the archive unless one of the options \-a, \-b | |
145 | or \-i is specified. | |
146 | .TP | |
147 | \-T | |
148 | Select and/or name archive members using only the first fifteen characters | |
149 | of the archive member or command line file name. | |
150 | The historic archive format had sixteen bytes for the name, but some | |
151 | historic archiver and loader implementations were unable to handle names | |
152 | that used the entire space. | |
153 | This means that file names that are not unique in their first fifteen | |
154 | characters can subsequently be confused. | |
155 | A warning message is printed to the standard error output if any file | |
156 | names are truncated. | |
157 | (See | |
158 | .IR ar (5) | |
159 | for more information.) | |
160 | .TP | |
161 | \-t | |
162 | List the specified files in the order in which they appear in the archive, | |
163 | each on a separate line. | |
164 | If no files are specified, all files in the archive are listed. | |
165 | .TP | |
166 | \-u | |
167 | Update files. | |
168 | When used with the \-r option, files in the archive will be replaced | |
169 | only if the disk file has a newer modification time than the file in | |
170 | the archive. | |
171 | When used with the \-x option, files in the archive will be extracted | |
172 | only if the archive file has a newer modification time than the file | |
173 | on disk. | |
174 | .TP | |
175 | \-v | |
176 | Provide verbose output. | |
177 | When used with the \-d, \-m, \-q or \-x options, | |
178 | .I ar | |
179 | gives a file-by-file description of the archive modification. | |
180 | This description consists of three, white-space separated fields: the | |
181 | option letter, a dash (``-'') and the file name. | |
182 | When used with the \-r option, | |
183 | .I ar | |
184 | displays the description as above, but the initial letter is an ``a'' if | |
185 | the file is added to the archive and an ``r'' if the file replaces a file | |
186 | already in the archive. | |
187 | .IP | |
188 | When used with the \-p option, | |
189 | the name of each printed file is written to the standard output before | |
190 | the contents of the file, preceded by a single newline character, and | |
191 | followed by two newline characters, enclosed in less-than (``<'') and | |
192 | greater-than (``>'') characters. | |
193 | .IP | |
194 | When used with the \-t option, | |
195 | .I ar | |
196 | displays an ``ls -l'' style listing of information about the members of | |
197 | the archive. | |
198 | This listing consists of eight, white-space separated fields: | |
199 | the file permissions (see | |
200 | .IR strmode (3)), | |
201 | the decimal user and group ID's, separated by a single slash (``/''), | |
202 | the file size (in bytes), the file modification time (in the | |
203 | .IR date (1) | |
204 | format ``%b %e %H:%M %Y''), and the name of the file. | |
205 | .TP | |
206 | \-x | |
207 | Extract the specified archive members into the files named by the command | |
208 | line arguments. | |
209 | If no members are specified, all the members of the archive are extracted into | |
210 | the current directory. | |
211 | .IP | |
212 | If the file does not exist, it is created; if it does exist, the owner | |
213 | and group will be unchanged. | |
214 | The file access and modification times are the time of the extraction | |
215 | (but see the \-o option). | |
216 | The file permissions will be set to those of the file when it was entered | |
217 | into the archive; this will fail if the user is not the owner of the | |
218 | extracted file or the super-user. | |
219 | .PP | |
220 | The | |
221 | .I ar | |
222 | utility exits 0 on success, and >0 if an error occurs. | |
223 | .SH ENVIRONMENT | |
224 | .TP | |
225 | TMPDIR | |
226 | The pathname of the directory to use when creating temporary files. | |
227 | .SH FILES | |
228 | .TP 14 | |
229 | /tmp | |
230 | default temporary file directory | |
231 | .TP 14 | |
232 | ar.XXXXXX | |
233 | temporary file names | |
234 | .SH COMPATIBILITY | |
235 | By default, | |
236 | .I ar | |
237 | writes archives that may be incompatible with historic archives, as | |
238 | the format used for storing archive members with names longer than | |
239 | fifteen characters has changed. | |
240 | This implementation of | |
241 | .I ar | |
242 | is backward compatible with previous versions of | |
243 | .I ar | |
244 | in that it can read and write (using the \-T option) historic archives. | |
245 | The \-T option is provided for compatibility only, and will be deleted | |
246 | in a future release. | |
247 | See | |
248 | .IR ar (5) | |
249 | for more information. | |
250 | .SH STANDARDS | |
251 | The | |
252 | .I ar | |
253 | utility is expected to offer a superset of the POSIX 1003.2 functionality. | |
254 | .SH "SEE ALSO" | |
255 | ld(1), ranlib(1), strmode(3), ar(5) |