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