1AR(1P) POSIX Programmer's Manual AR(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 ar - create and maintain library archives
13
15 ar -d[-v] archive file ...
16 ar -m [-v] archive file ...
20 ar -m -a[-v] posname archive file ...
22 ar -m -b[-v] posname archive file ...
24 ar -m -i[-v] posname archive file ...
26 ar -p[-v][-s]archive [file ...]
28 ar -q[-cv] archive file ...
32 ar -r[-cuv] archive file ...
34 ar -r -a[-cuv] posname archive file ...
38 ar -r -b[-cuv] posname archive file ...
40 ar -r -i[-cuv] posname archive file ...
42 ar -t[-v][-s]archive [file ...]
44 ar -x[-v][-sCT]archive [file ...]
46
49 The ar utility is part of the Software Development Utilities option.
50 The ar utility can be used to create and maintain groups of files com‐
52 bined into an archive. Once an archive has been created, new files can
53 be added, and existing files in an archive can be extracted, deleted,
54 or replaced. When an archive consists entirely of valid object files,
55 the implementation shall format the archive so that it is usable as a
56 library for link editing (see c99 and fort77). When some of the
57 archived files are not valid object files, the suitability of the ar‐
58 chive for library use is undefined. If an archive consists entirely of
59 printable files, the entire archive shall be printable.
60 When ar creates an archive, it creates administrative information indi‐
62 cating whether a symbol table is present in the archive. When there is
63 at least one object file that ar recognizes as such in the archive, an
64 archive symbol table shall be created in the archive and maintained by
65 ar; it is used by the link editor to search the archive. Whenever the
66 ar utility is used to create or update the contents of such an archive,
67 the symbol table shall be rebuilt. The -s option shall force the symbol
68 table to be rebuilt.
69 All file operands can be pathnames. However, files within archives
71 shall be named by a filename, which is the last component of the path‐
72 name used when the file was entered into the archive. The comparison of
73 file operands to the names of files in archives shall be performed by
74 comparing the last component of the operand to the name of the file in
75 the archive.
76 It is unspecified whether multiple files in the archive may be identi‐
78 cally named. In the case of such files, however, each file and posname
79 operand shall match only the first file in the archive having a name
80 that is the same as the last component of the operand.
81
83 The ar utility shall conform to the Base Definitions volume of
84 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
85 The following options shall be supported:
87 -a Position new files in the archive after the file named by the
89 posname operand.
90 -b Position new files in the archive before the file named by the
92 posname operand.
93 -c Suppress the diagnostic message that is written to standard
95 error by default when the archive archive is created.
96 -C Prevent extracted files from replacing like-named files in the
98 file system. This option is useful when -T is also used, to pre‐
99 vent truncated filenames from replacing files with the same pre‐
100 fix.
101 -d Delete one or more files from archive.
103 -i Position new files in the archive before the file in the archive
105 named by the posname operand (equivalent to -b).
106 -m Move the named files in the archive. The -a, -b, or -i options
108 with the posname operand indicate the position; otherwise, move
109 the names files in the archive to the end of the archive.
110 -p Write the contents of the files in the archive named by file op‐
112 erands from archive to the standard output. If no file operands
113 are specified, the contents of all files in the archive shall be
114 written in the order of the archive.
115 -q Append the named files to the end of the archive. In this case
117 ar does not check whether the added files are already in the ar‐
118 chive. This is useful to bypass the searching otherwise done
119 when creating a large archive piece by piece.
120 -r Replace or add files to archive. If the archive named by archive
122 does not exist, a new archive shall be created and a diagnostic
123 message shall be written to standard error (unless the -c option
124 is specified). If no files are specified and the archive exists,
125 the results are undefined. Files that replace existing files in
126 the archive shall not change the order of the archive. Files
127 that do not replace existing files in the archive shall be
128 appended to the archive unless a -a, -b, or -i option specifies
129 another position.
130 -s Force the regeneration of the archive symbol table even if ar is
132 not invoked with an option that modifies the archive contents.
133 This option is useful to restore the archive symbol table after
134 it has been stripped; see strip.
135 -t Write a table of contents of archive to the standard output.
137 The files specified by the file operands shall be included in
138 the written list. If no file operands are specified, all files
139 in archive shall be included in the order of the archive.
140 -T Allow filename truncation of extracted files whose archive names
142 are longer than the file system can support. By default,
143 extracting a file with a name that is too long shall be an
144 error; a diagnostic message shall be written and the file shall
145 not be extracted.
146 -u Update older files in the archive. When used with the -r option,
148 files in the archive shall be replaced only if the corresponding
149 file has a modification time that is at least as new as the mod‐
150 ification time of the file in the archive.
151 -v Give verbose output. When used with the option characters -d,
153 -r, or -x, write a detailed file-by-file description of the ar‐
154 chive creation and maintenance activity, as described in the
155 STDOUT section.
156 When used with -p, write the name of the file in the archive to the
158 standard output before writing the file in the archive itself to the
159 standard output, as described in the STDOUT section.
160 When used with -t, include a long listing of information about the
162 files in the archive, as described in the STDOUT section.
163 -x Extract the files in the archive named by the file operands from
165 archive. The contents of the archive shall not be changed. If no
166 file operands are given, all files in the archive shall be
167 extracted. The modification time of each file extracted shall be
168 set to the time the file is extracted from the archive.
169
172 The following operands shall be supported:
173 archive
175 A pathname of the archive.
176 file A pathname. Only the last component shall be used when comparing
178 against the names of files in the archive. If two or more file
179 operands have the same last pathname component (basename), the
180 results are unspecified. The implementation's archive format
181 shall not truncate valid filenames of files added to or replaced
182 in the archive.
183 posname
185 The name of a file in the archive, used for relative position‐
186 ing; see options -m and -r.
187
190 Not used.
191
193 The archive named by archive shall be a file in the format created by
194 ar -r.
195
197 The following environment variables shall affect the execution of ar:
198 LANG Provide a default value for the internationalization variables
200 that are unset or null. (See the Base Definitions volume of
201 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
202 ables for the precedence of internationalization variables used
203 to determine the values of locale categories.)
204 LC_ALL If set to a non-empty string value, override the values of all
206 the other internationalization variables.
207 LC_CTYPE
209 Determine the locale for the interpretation of sequences of
210 bytes of text data as characters (for example, single-byte as
211 opposed to multi-byte characters in arguments and input files).
212 LC_MESSAGES
214 Determine the locale that should be used to affect the format
215 and contents of diagnostic messages written to standard error.
216 LC_TIME
218 Determine the format and content for date and time strings writ‐
219 ten by ar -tv.
220 NLSPATH
222 Determine the location of message catalogs for the processing of
223 LC_MESSAGES .
224 TMPDIR Determine the pathname that overrides the default directory for
226 temporary files, if any.
227 TZ Determine the timezone used to calculate date and time strings
229 written by ar -tv. If TZ is unset or null, an unspecified
230 default timezone shall be used.
231
234 Default.
235
237 If the -d option is used with the -v option, the standard output format
238 shall be:
239 "d - %s\n", <file>
242 where file is the operand specified on the command line.
244 If the -p option is used with the -v option, ar shall precede the con‐
246 tents of each file with:
247 "\n<%s>\n\n", <file>
250 where file is the operand specified on the command line, if file oper‐
252 ands were specified, and the name of the file in the archive if they
253 were not.
254 If the -r option is used with the -v option:
256 * If file is already in the archive, the standard output format shall
258 be:
259 "r - %s\n", <file>
262 where <file> is the operand specified on the command line.
264 * If file is not already in the archive, the standard output format
266 shall be:
267 "a - %s\n", <file>
270 where <file> is the operand specified on the command line.
272 If the -t option is used, ar shall write the names of the files in the
274 archive to the standard output in the format:
275 "%s\n", <file>
278 where file is the operand specified on the command line, if file oper‐
280 ands were specified, or the name of the file in the archive if they
281 were not.
282 If the -t option is used with the -v option, the standard output format
284 shall be:
285 "%s %u/%u %u %s %d %d:%d %d %s\n", <member mode>, <user ID>,
288 <group ID>, <number of bytes in member>,
289 <abbreviated month>, <day-of-month>, <hour>,
290 <minute>, <year>, <file>
291 where:
293 <file> Shall be the operand specified on the command line, if file op‐
295 erands were specified, or the name of the file in the archive if
296 they were not.
297 <member mode>
299 Shall be formatted the same as the <file mode> string defined in
301 the STDOUT section of ls, except that the first character, the
302 <entry type>, is not used; the string represents the file mode
303 of the file in the archive at the time it was added to or
304 replaced in the archive.
305 The following represent the last-modification time of a file when it
308 was most recently added to or replaced in the archive:
309 <abbreviated month>
311 Equivalent to the format of the %b conversion specification for‐
313 mat in date.
314 <day-of-month>
316 Equivalent to the format of the %e conversion specification for‐
318 mat in date.
319 <hour> Equivalent to the format of the %H conversion specification for‐
321 mat in date.
322 <minute>
324 Equivalent to the format of the %M conversion specification for‐
325 mat in date.
326 <year> Equivalent to the format of the %Y conversion specification for‐
328 mat in date.
329 When LC_TIME does not specify the POSIX locale, a different format and
332 order of presentation of these fields relative to each other may be
333 used in a format appropriate in the specified locale.
334 If the -x option is used with the -v option, the standard output format
336 shall be:
337 "x - %s\n", <file>
340 where file is the operand specified on the command line, if file oper‐
342 ands were specified, or the name of the file in the archive if they
343 were not.
344
346 The standard error shall be used only for diagnostic messages. The
347 diagnostic message about creating a new archive when -c is not speci‐
348 fied shall not modify the exit status.
349
351 Archives are files with unspecified formats.
352
354 None.
355
357 The following exit values shall be returned:
358 0 Successful completion.
360 >0 An error occurred.
362
365 Default.
366 The following sections are informative.
368
370 None.
371
373 None.
374
376 The archive format is not described. It is recognized that there are
377 several known ar formats, which are not compatible. The ar utility is
378 included, however, to allow creation of archives that are intended for
379 use only on one machine. The archive is specified as a file, and it can
380 be moved as a file. This does allow an archive to be moved from one
381 machine to another machine that uses the same implementation of ar.
382 Utilities such as pax (and its forebears tar and cpio) also provide
384 portable "archives". This is a not a duplication; the ar utility is
385 included to provide an interface primarily for make and the compilers,
386 based on a historical model.
387 In historical implementations, the -q option (available on XSI-conform‐
389 ing systems) is known to execute quickly because ar does not check on
390 whether the added members are already in the archive. This is useful to
391 bypass the searching otherwise done when creating a large archive
392 piece-by-piece. These remarks may but need not remain true for a brand
393 new implementation of this utility; hence, these remarks have been
394 moved into the RATIONALE.
395 BSD implementations historically required applications to provide the
397 -s option whenever the archive was supposed to contain a symbol table.
398 As in this volume of IEEE Std 1003.1-2001, System V historically cre‐
399 ates or updates an archive symbol table whenever an object file is
400 removed from, added to, or updated in the archive.
401 The OPERANDS section requires what might seem to be true without speci‐
403 fying it: the archive cannot truncate the filenames below {NAME_MAX}.
404 Some historical implementations do so, however, causing unexpected
405 results for the application. Therefore, this volume of
406 IEEE Std 1003.1-2001 makes the requirement explicit to avoid misunder‐
407 standings.
408 According to the System V documentation, the options -dmpqrtx are not
410 required to begin with a hyphen ( '-' ). This volume of
411 IEEE Std 1003.1-2001 requires that a conforming application use the
412 leading hyphen.
413 The archive format used by the 4.4 BSD implementation is documented in
415 this RATIONALE as an example: A file created by ar begins with the
416 "magic" string "!<arch>\n" . The rest of the archive is made up of
417 objects, each of which is composed of a header for a file, a possible
418 filename, and the file contents. The header is portable between machine
419 architectures, and, if the file contents are printable, the archive is
420 itself printable.
421 The header is made up of six ASCII fields, followed by a two-character
423 trailer. The fields are the object name (16 characters), the file last
424 modification time (12 characters), the user and group IDs (each 6 char‐
425 acters), the file mode (8 characters), and the file size (10 charac‐
426 ters). All numeric fields are in decimal, except for the file mode,
427 which is in octal.
428 The modification time is the file st_mtime field. The user and group
430 IDs are the file st_uid and st_gid fields. The file mode is the file
431 st_mode field. The file size is the file st_size field. The two-byte
432 trailer is the string "`<newline>" .
433 Only the name field has any provision for overflow. If any filename is
435 more than 16 characters in length or contains an embedded space, the
436 string "#1/" followed by the ASCII length of the name is written in the
437 name field. The file size (stored in the archive header) is incremented
438 by the length of the name. The name is then written immediately follow‐
439 ing the archive header.
440 Any unused characters in any of these fields are written as <space>s.
442 If any fields are their particular maximum number of characters in
443 length, there is no separation between the fields.
444 Objects in the archive are always an even number of bytes long; files
446 that are an odd number of bytes long are padded with a <newline>,
447 although the size in the header does not reflect this.
448 The ar utility description requires that (when all its members are
450 valid object files) ar produce an object code library, which the link‐
451 age editor can use to extract object modules. If the linkage editor
452 needs a symbol table to permit random access to the archive, ar must
453 provide it; however, ar does not require a symbol table.
454 The BSD -o option was omitted. It is a rare conforming application that
456 uses ar to extract object code from a library with concern for its mod‐
457 ification time, since this can only be of importance to make. Hence,
458 since this functionality is not deemed important for applications
459 portability, the modification time of the extracted files is set to the
460 current time.
461 There is at least one known implementation (for a small computer) that
463 can accommodate only object files for that system, disallowing mixed
464 object and other files. The ability to handle any type of file is not
465 only historical practice for most implementations, but is also a rea‐
466 sonable expectation.
467 Consideration was given to changing the output format of ar -tv to the
469 same format as the output of ls -l. This would have made parsing the
470 output of ar the same as that of ls. This was rejected in part because
471 the current ar format is commonly used and changes would break histori‐
472 cal usage. Second, ar gives the user ID and group ID in numeric format
473 separated by a slash. Changing this to be the user name and group name
474 would not be correct if the archive were moved to a machine that con‐
475 tained a different user database. Since ar cannot know whether the ar‐
476 chive was generated on the same machine, it cannot tell what to report.
477 The text on the -ur option combination is historical practice-since one
479 filename can easily represent two different files (for example, /a/foo
480 and /b/foo), it is reasonable to replace the file in the archive even
481 when the modification time in the archive is identical to that in the
482 file system.
483
485 None.
486
488 c99, date, fort77, pax, strip the Base Definitions volume of
489 IEEE Std 1003.1-2001, Chapter 13, Headers, <unistd.h> description of
490 {POSIX_NO_TRUNC}
491
493 Portions of this text are reprinted and reproduced in electronic form
494 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
495 -- Portable Operating System Interface (POSIX), The Open Group Base
496 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
497 Electrical and Electronics Engineers, Inc and The Open Group. In the
498 event of any discrepancy between this version and the original IEEE and
499 The Open Group Standard, the original IEEE and The Open Group Standard
500 is the referee document. The original Standard can be obtained online
501 at http://www.opengroup.org/unix/online.html .
502IEEE/The Open Group 2003 AR(1P)