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