| blob | ed2bde0c924b42382d566c057c4d285babca2ec0 |
1 '\" te
2 .\" Copyright 1989 AT&T
3 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
4 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/.
6 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text
7 .\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical
8 .\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
9 .\" This notice shall appear on any product containing this material.
10 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
11 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
12 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
13 .TH AR 1 "Sep 10, 2013"
14 .SH NAME
15 ar \- maintain portable archive or library
16 .SH SYNOPSIS
17 .LP
18 .nf
19 \fB/usr/bin/ar\fR \fB-d\fR [\fB-Vv\fR] \fIarchive\fR \fIfile\fR...
20 .fi
22 .LP
23 .nf
24 \fB/usr/bin/ar\fR \fB-m\fR [\fB-abiVv\fR] [\fIposname\fR] \fIarchive\fR \fIfile\fR...
25 .fi
27 .LP
28 .nf
29 \fB/usr/bin/ar\fR \fB-p\fR [\fB-sVv\fR] \fIarchive\fR [\fIfile\fR]...
30 .fi
32 .LP
33 .nf
34 \fB/usr/bin/ar\fR \fB-q\fR [\fB-cVv\fR] \fIarchive\fR \fIfile\fR...
35 .fi
37 .LP
38 .nf
39 \fB/usr/bin/ar\fR \fB-r\fR [\fB-abciuVv\fR] [\fIposname\fR] \fIarchive\fR \fIfile\fR...
40 .fi
42 .LP
43 .nf
44 \fB/usr/bin/ar\fR \fB-t\fR [\fB-sVv\fR] \fIarchive\fR [\fIfile\fR]...
45 .fi
47 .LP
48 .nf
49 \fB/usr/bin/ar\fR \fB-x\fR [\fB-CsTVv\fR] \fIarchive\fR [\fIfile\fR]...
50 .fi
51 .SH DESCRIPTION
52 .sp
53 .LP
54 The \fBar\fR utility maintains groups of files combined into a single archive
55 file. Its main use is to create and update library files. However, it can be
56 used for any similar purpose. The magic string and the file headers used by
57 \fBar\fR consist of printable \fBASCII\fR characters. If an archive is composed
58 of printable files, the entire archive is printable.
59 .sp
60 .LP
61 When \fBar\fR creates an archive, it creates headers in a format that is
62 portable across all machines. The portable archive format and structure are
63 described in detail in \fBar.h\fR(3HEAD). The archive symbol table described
64 there is used by the link editor \fBld\fR(1) to effect multiple passes over
65 libraries of object files in an efficient manner. An archive symbol table is
66 only created and maintained by \fBar\fR when there is at least one object file
67 in the archive. The archive symbol table is in a specially named file that is
68 always the first file in the archive. This file is never mentioned or
69 accessible to the user. Whenever the \fBar\fR command is used to create or
70 update the contents of such an archive, the symbol table is rebuilt. The
71 \fB-s\fR option described below forces the symbol table to be rebuilt.
72 .SH OPTIONS
73 .sp
74 .LP
75 The following options are supported:
76 .sp
77 .ne 2
78 .na
79 \fB\fB-a\fR\fR
80 .ad
81 .RS 6n
82 Positions new \fIfile\fRs in \fIarchive\fR after the file named by the
83 \fIposname\fR operand.
84 .RE
86 .sp
87 .ne 2
88 .na
89 \fB\fB-b\fR\fR
90 .ad
91 .RS 6n
92 Positions new \fIfile\fRs in \fIarchive\fR before the file named by the
93 \fIposname\fR operand.
94 .RE
96 .sp
97 .ne 2
98 .na
99 \fB\fB-c\fR\fR
100 .ad
101 .RS 6n
102 Suppresses the diagnostic message that is written to standard error by default
103 when \fIarchive\fR is created.
104 .RE
106 .sp
107 .ne 2
108 .na
109 \fB\fB-C\fR\fR
110 .ad
111 .RS 6n
112 Prevents extracted files from replacing like-named files in the file system.
113 This option is useful when \fB-T\fR is also used to prevent truncated file
114 names from replacing files with the same prefix.
115 .RE
117 .sp
118 .ne 2
119 .na
120 \fB\fB-d\fR\fR
121 .ad
122 .RS 6n
123 Deletes one or more \fIfile\fRs from \fIarchive\fR.
124 .RE
126 .sp
127 .ne 2
128 .na
129 \fB\fB-i\fR\fR
130 .ad
131 .RS 6n
132 Positions new \fIfile\fRs in \fIarchive\fR before the file named by the
133 \fIposname\fR operand. This option is quivalent to \fB-b\fR.
134 .RE
136 .sp
137 .ne 2
138 .na
139 \fB\fB-m\fR\fR
140 .ad
141 .RS 6n
142 Moves \fIfile\fRs. If \fB-a\fR, \fB-b\fR, or \fB-i\fR with the \fIposname\fR
143 operand are specified, the \fB-m\fR option moves \fIfile\fRs to the new
144 position. Otherwise, \fB-m\fR moves \fIfile\fRs to the end of \fIarchive\fR.
145 .RE
147 .sp
148 .ne 2
149 .na
150 \fB\fB-p\fR\fR
151 .ad
152 .RS 6n
153 Prints the contents of \fIfile\fRs in \fIarchive\fR to standard output. If no
154 \fIfile\fRs are specified, the contents of all files in \fIarchive\fR are
155 written in the order of the archive.
156 .RE
158 .sp
159 .ne 2
160 .na
161 \fB\fB-q\fR\fR
162 .ad
163 .RS 6n
164 Quickly appends \fIfile\fRs to the end of \fIarchive\fR. Positioning options
165 \fB-a\fR, \fB-b\fR, and \fB-i\fR are invalid. The command does not check
166 whether the added \fIfile\fRs are already in \fIarchive\fR. This option is
167 useful to avoid quadratic behavior when creating a large archive
168 piece-by-piece.
169 .RE
171 .sp
172 .ne 2
173 .na
174 \fB\fB-r\fR\fR
175 .ad
176 .RS 6n
177 Replaces or adds \fIfile\fRs in \fIarchive\fR. If \fIarchive\fR does not exist,
178 a new archive file is created and a diagnostic message is written to standard
179 error, unless the \fB-c\fR option is specified. If no \fIfile\fRs are specified
180 and the \fIarchive\fR exists, the results are undefined. Files that replace
181 existing files do not change the order of the archive. If the \fB-u\fR option
182 is used with the \fB-r\fR option, only those files with dates of modification
183 later than the archive files are replaced. If the \fB-a\fR, \fB-b\fR, or
184 \fB-i\fR option is used, the \fIposname\fR argument must be present and
185 specifies that new files are to be placed after (\fB-a\fR) or before (\fB-b\fR
186 or \fB-i\fR) \fIposname\fR. Otherwise, the new files are placed at the end.
187 .RE
189 .sp
190 .ne 2
191 .na
192 \fB\fB-s\fR\fR
193 .ad
194 .RS 6n
195 Forces the regeneration of the archive symbol table even if \fBar\fR is not
196 invoked with an option that will modify the archive contents. This command is
197 useful to restore the archive symbol table after the \fBstrip\fR(1) command has
198 been used on the archive.
199 .RE
201 .sp
202 .ne 2
203 .na
204 \fB\fB-t\fR\fR
205 .ad
206 .RS 6n
207 Prints a table of contents of \fIarchive\fR. The files specified by the
208 \fIfile\fR operands are included in the written list. If no \fIfile\fR operands
209 are specified, all files in \fIarchive\fR are included in the order of the
210 archive.
211 .RE
213 .sp
214 .ne 2
215 .na
216 \fB\fB-T\fR\fR
217 .ad
218 .RS 6n
219 Allows file name truncation of extracted files whose archive names are longer
220 than the file system can support. By default, extracting a file with a name
221 that is too long is an error. In that case, a diagnostic message is written and
222 the file is not extracted.
223 .RE
225 .sp
226 .ne 2
227 .na
228 \fB\fB-u\fR\fR
229 .ad
230 .RS 6n
231 Updates older files. When used with the \fB-r\fR option, files within
232 \fIarchive\fR are replaced only if the corresponding \fIfile\fR has a
233 modification time that is at least as new as the modification time of the file
234 within \fIarchive\fR.
235 .RE
237 .sp
238 .ne 2
239 .na
240 \fB\fB-v\fR\fR
241 .ad
242 .RS 6n
243 Gives verbose output. When used with options \fB-d\fR, \fB-r\fR, or \fB-x\fR,
244 the \fB-v\fR option writes a detailed file-by-file description of the archive
245 creation and the constituent \fIfile\fRs, and maintenance activity. When used
246 with \fB-p\fR, \fB-v\fR writes the name of the file to the standard output
247 before writing the file itself to the standard output. When used with \fB-t\fR,
248 \fB-v\fR includes a long listing of information about the files within the
249 archive. When used with \fB-x\fR, \fB-v\fR prints the filename preceding each
250 extraction.
251 .RE
253 .sp
254 .ne 2
255 .na
256 \fB\fB-V\fR\fR
257 .ad
258 .RS 6n
259 Prints its version number on standard error.
260 .RE
262 .SH OPERANDS
263 .sp
264 .LP
265 The following operands are supported:
266 .sp
267 .ne 2
268 .na
269 \fB\fIarchive\fR\fR
270 .ad
271 .RS 11n
272 A path name of the archive file.
273 .RE
275 .sp
276 .ne 2
277 .na
278 \fB\fIfile\fR\fR
279 .ad
280 .RS 11n
281 A path name. Only the last component is used when comparing against the names
282 of files in the archive. If two or more \fIfile\fR operands have the same last
283 path name component (see \fBbasename\fR(1)), the results are unspecified. The
284 implementation's archive format will not truncate valid file names of files
285 added to or replaced in the archive.
286 .RE
288 .sp
289 .ne 2
290 .na
291 \fB\fIposname\fR\fR
292 .ad
293 .RS 11n
294 The name of a file in the archive file, used for relative positioning. See
295 options \fB-m\fR and \fB-r\fR.
296 .RE
298 .SH ENVIRONMENT VARIABLES
299 .sp
300 .LP
301 See \fBenviron\fR(5) for descriptions of the following environment variables
302 that affect the execution of \fBar\fR: \fBLANG\fR, \fBLC_ALL\fR,
303 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, \fBLC_TIME\fR, and \fBNLSPATH\fR.
304 .sp
305 .ne 2
306 .na
307 \fB\fBTMPDIR\fR\fR
308 .ad
309 .RS 10n
310 Determine the pathname that overrides the default directory for temporary
311 files, if any.
312 .RE
314 .sp
315 .ne 2
316 .na
317 \fB\fBTZ\fR\fR
318 .ad
319 .RS 10n
320 Determine the timezone used to calculate date and time strings written by
321 \fBar\fR \fB-tv\fR. If \fBTZ\fR is unset or null, an unspecified default
322 timezone is used.
323 .RE
325 .SH EXIT STATUS
326 .sp
327 .LP
328 The following exit values are returned:
329 .sp
330 .ne 2
331 .na
332 \fB\fB0\fR\fR
333 .ad
334 .RS 6n
335 Successful completion.
336 .RE
338 .sp
339 .ne 2
340 .na
341 \fB\fB>0\fR\fR
342 .ad
343 .RS 6n
344 An error occurred.
345 .RE
347 .SH ATTRIBUTES
348 .sp
349 .LP
350 See \fBattributes\fR(5) for descriptions of the following attributes:
351 .SS "\fB/usr/bin/ar\fR"
352 .sp
354 .sp
355 .TS
356 box;
357 c | c
358 l | l .
359 ATTRIBUTE TYPE ATTRIBUTE VALUE
360 _
361 Interface Stability Committed
362 .TE
364 .SH SEE ALSO
365 .sp
366 .LP
367 \fBbasename\fR(1), \fBcpio\fR(1), \fBld\fR(1), \fBlorder\fR(1), \fBstrip\fR(1),
368 \fBtar\fR(1), \fBar.h\fR(3HEAD), \fBa.out\fR(4), \fBattributes\fR(5),
369 \fBenviron\fR(5), \fBstandards\fR(5)
370 .SH NOTES
371 .sp
372 .LP
373 If the same file is mentioned twice in an argument list, it may be put in the
374 archive twice.
375 .sp
376 .LP
377 By convention, archives are suffixed with "\fB\&.a\fR".
378 .sp
379 .LP
380 When inserting \fBELF\fR objects into an archive file, \fBar\fR might add
381 "\fB\en\fR" characters to pad these objects to an 8-byte boundary. Such padding
382 improves the efficiency with which \fBld\fR(1) can access the archive. Only
383 \fBELF\fR object files are padded in this way. Other archive members are not
384 altered. When an object with such padding is extracted from an archive, the
385 padding is not included in the resulting output.