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 | .\" | |
5504c5d3 | 9 | .\" @(#)ar.1 6.7 (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 | |
616b39cf KB |
18 | ar -d [-sv] archive file ... |
19 | ar -m [-sv] archive file ... | |
20 | ar -m [-abisv] position archive file ... | |
21 | ar -p [-sv] archive [file ...] | |
22 | ar -q [-csv] archive file ... | |
23 | ar -r [-cusv] archive file ... | |
24 | ar -r [-abciusv] position archive file ... | |
25 | ar -t [-sv] archive [file ...] | |
26 | ar -x [-ousv] 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. | |
41 | All informational and error messages use the file name as found in the | |
42 | archive, not the path listed on the command line. | |
43 | If multiple files in the archive have the same name, and paths are listed | |
44 | on the command line to ``select'' archive files for an operation, only the | |
45 | .B first | |
46 | file with a matching name will be selected. | |
47 | .PP | |
48 | The normal use of | |
49 | .I ar | |
50 | is for the creation and maintenance of libraries suitable for use with | |
51 | the loader (see | |
52 | .IR ld (1)) | |
53 | although it is not restricted to this purpose. | |
54 | The options are as follows: | |
55 | .TP | |
56 | \-a | |
57 | A positioning modifier used with the options \-r and \-m. | |
58 | The files are entered or moved | |
59 | .B after | |
60 | the archive member | |
61 | .IR position , | |
62 | which must be specified. | |
63 | .TP | |
64 | \-b | |
65 | A positioning modifier used with the options \-r and \-m. | |
66 | The files are entered or moved | |
67 | .B before | |
68 | the archive member | |
69 | .IR position , | |
70 | which must be specified. | |
71 | .TP | |
72 | \-c | |
73 | Whenever an archive is created, an informational message to that effect | |
74 | is written to standard error. | |
75 | If the \-c option is specified, | |
76 | .I ar | |
77 | creates the archive silently. | |
78 | .TP | |
79 | \-d | |
80 | Delete the specified archive files. | |
81 | .TP | |
82 | \-i | |
83 | Identical to the \-b option. | |
84 | .TP | |
85 | \-m | |
86 | Move the specified archive files within the archive. | |
87 | If one of the options \-a, \-b or \-i are specified, the files are moved | |
88 | before or after the | |
89 | .I position | |
90 | file in the archive. | |
91 | If none of those options are specified, the files are moved | |
92 | to the end of the archive. | |
93 | .TP | |
94 | \-o | |
95 | Set the access and modification times of extracted files to the | |
96 | modification time of the file when it was entered into the archive. | |
97 | This will fail if the user is not the owner of the extracted file | |
98 | or the super-user. | |
99 | .TP | |
100 | \-p | |
101 | Write the contents of the specified archive files to the standard output. | |
102 | If no files are specified, the contents of all the files in the archive | |
103 | are written in the order they appear in the archive. | |
104 | .TP | |
105 | \-q | |
106 | (Quickly) append the specified files to the archive. | |
107 | If the archive does not exist a new archive file is created. | |
108 | Much faster than the \-r option, when creating a large archive | |
109 | piece-by-piece, as no checking is done to see if the files already | |
110 | exist in the archive. | |
111 | .TP | |
112 | \-r | |
113 | Replace or add the specified files to the archive. | |
114 | If the archive does not exist a new archive file is created. | |
115 | Files that replace existing files do not change the order of the files | |
116 | within the archive. | |
117 | New files are appended to the archive unless one of the options \-a, \-b | |
118 | or \-i is specified. | |
119 | .TP | |
616b39cf | 120 | \-s |
5504c5d3 KB |
121 | Truncate file names to fit in the historical archive file format. |
122 | The historic format had sixteen bytes for the name, but historic | |
123 | implementations couldn't handle names that used the entire space, | |
124 | so this option causes file names longer than fifteen characters to | |
125 | be truncated. | |
126 | This means that file names that are not unique in their first fifteen | |
616b39cf KB |
127 | characters can subsequently be confused. |
128 | A warning message is printed to the standard error output if any file | |
129 | names are truncated. | |
130 | (See | |
131 | .IR ar (5) | |
132 | for more information.) | |
133 | .TP | |
bdba1630 KB |
134 | \-t |
135 | List the specified files in the order in which they appear in the archive, | |
136 | each on a separate line. | |
137 | If no files are specified, all files in the archive are listed. | |
138 | .TP | |
139 | \-u | |
140 | Update files. | |
141 | When used with the \-r option, files in the archive will be replaced | |
142 | only if the disk file has a newer modification time than the file in | |
143 | the archive. | |
144 | When used with the \-x option, files in the archive will be extracted | |
145 | only if the archive file has a newer modification time than the file | |
146 | on disk. | |
147 | .TP | |
148 | \-v | |
149 | Provide verbose output. | |
150 | When used with the \-d, \-m, \-q or \-x options, | |
151 | .I ar | |
152 | gives a file-by-file description of the archive modification. | |
153 | This description consists of three, white-space separated fields: the | |
154 | option letter, a dash (``-'') and the file name. | |
155 | When used with the \-r option, | |
156 | .I ar | |
157 | displays the description as above, but the initial letter is an ``a'' if | |
158 | the file is added to the archive and an ``r'' if the file replaces a file | |
159 | already in the archive. | |
160 | .IP | |
161 | When used with the \-p option, | |
162 | the name of each printed file is written to the standard output before | |
163 | the contents of the file, on a line by itself, enclosed in less-than | |
164 | (``<'') and greater-than (``>'') characters. | |
165 | .IP | |
166 | When used with the \-t option, | |
167 | .I ar | |
168 | displays an ``ls -l'' style listing of information about the files in | |
169 | the archive. | |
170 | This listing consists of eight, white-space separated fields: | |
171 | the file permissions (see | |
172 | .IR strmode (3)), | |
173 | the decimal user and group ID's, separated by a single slash (``/''), | |
174 | the file size (in bytes), the file modification time (in the | |
175 | .IR date (1) | |
176 | format ``%b %e %H:%M %Y''), and the name of the file. | |
177 | .TP | |
178 | \-x | |
179 | Extract the specified files into the files named by the command line | |
180 | arguments. | |
181 | If no files are specified, all the files in the archive are extracted into | |
182 | the current directory. | |
183 | .IP | |
184 | If the file does not exist, it is created; if it does exist, the owner | |
185 | and group will be unchanged. | |
186 | The file access and modification times are the time of the extraction | |
187 | (but see the \-o option). | |
188 | The file permissions will be set to those of the file when it was entered | |
189 | into the archive; this will fail if the user is not the owner of the | |
190 | extracted file or the super-user. | |
191 | .PP | |
b5dc1377 | 192 | The |
bdba1630 KB |
193 | .I ar |
194 | utility exits 0 on success, and >0 if an error occurs. | |
195 | .SH ENVIRONMENT | |
196 | .TP | |
197 | TMPDIR | |
198 | The pathname of the directory to use when creating temporary files. | |
199 | .PP | |
200 | .SH FILES | |
201 | .TP 14 | |
202 | /tmp | |
203 | default temporary file directory | |
204 | .TP 14 | |
205 | ar.XXXXXX | |
206 | temporary file names | |
207 | .SH "SEE ALSO" | |
208 | date(1), ld(1), ranlib(1), strmode(3), ar(5) |