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...
18 ar -m -a [-v] posname archive file...
19 ar -m -b [-v] posname archive file...
20 ar -m -i [-v] posname archive file...
21 ar -p [-v] [-s] archive [file...]
23 ar -q [-cv] archive file...
25 ar -r [-cuv] archive file...
27 ar -r -a [-cuv] posname archive file...
29 ar -r -b [-cuv] posname archive file...
30 ar -r -i [-cuv] posname archive file...
31 ar -t [-v] [-s] archive [file...]
33 ar -x [-v] [-sCT] archive [file...]
35
37 The ar utility is part of the Software Development Utilities option.
38 The ar utility can be used to create and maintain groups of files com‐
40 bined into an archive. Once an archive has been created, new files can
41 be added, and existing files in an archive can be extracted, deleted,
42 or replaced. When an archive consists entirely of valid object files,
43 the implementation shall format the archive so that it is usable as a
44 library for link editing (see c99 and fort77). When some of the
45 archived files are not valid object files, the suitability of the ar‐
46 chive for library use is undefined. If an archive consists entirely of
47 printable files, the entire archive shall be printable.
48 When ar creates an archive, it creates administrative information indi‐
50 cating whether a symbol table is present in the archive. When there is
51 at least one object file that ar recognizes as such in the archive, an
52 archive symbol table shall be created in the archive and maintained by
53 ar; it is used by the link editor to search the archive. Whenever the
54 ar utility is used to create or update the contents of such an archive,
55 the symbol table shall be rebuilt. The -s option shall force the symbol
56 table to be rebuilt.
57 All file operands can be pathnames. However, files within archives
59 shall be named by a filename, which is the last component of the path‐
60 name used when the file was entered into the archive. The comparison of
61 file operands to the names of files in archives shall be performed by
62 comparing the last component of the operand to the name of the file in
63 the archive.
64 It is unspecified whether multiple files in the archive may be identi‐
66 cally named. In the case of such files, however, each file and posname
67 operand shall match only the first file in the archive having a name
68 that is the same as the last component of the operand.
69
71 The ar utility shall conform to the Base Definitions volume of
72 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines, except for
73 Guideline 9.
74 The following options shall be supported:
76 -a Position new files in the archive after the file named by the
78 posname operand.
79 -b Position new files in the archive before the file named by
81 the posname operand.
82 -c Suppress the diagnostic message that is written to standard
84 error by default when the archive archive is created.
85 -C Prevent extracted files from replacing like-named files in
87 the file system. This option is useful when -T is also used,
88 to prevent truncated filenames from replacing files with the
89 same prefix.
90 -d Delete one or more files from archive.
92 -i Position new files in the archive before the file in the ar‐
94 chive named by the posname operand (equivalent to -b).
95 -m Move the named files in the archive. The -a, -b, or -i
97 options with the posname operand indicate the position; oth‐
98 erwise, move the names files in the archive to the end of the
99 archive.
100 -p Write the contents of the files in the archive named by file
102 operands from archive to the standard output. If no file op‐
103 erands are specified, the contents of all files in the ar‐
104 chive shall be written in the order of the archive.
105 -q Append the named files to the end of the archive. In this
107 case ar does not check whether the added files are already in
108 the archive. This is useful to bypass the searching other‐
109 wise done when creating a large archive piece by piece.
110 -r Replace or add files to archive. If the archive named by ar‐
112 chive does not exist, a new archive shall be created and a
113 diagnostic message shall be written to standard error (unless
114 the -c option is specified). If no files are specified and
115 the archive exists, the results are undefined. Files that
116 replace existing files in the archive shall not change the
117 order of the archive. Files that do not replace existing
118 files in the archive shall be appended to the archive unless
119 a -a, -b, or -i option specifies another position.
120 -s Force the regeneration of the archive symbol table even if ar
122 is not invoked with an option that modifies the archive con‐
123 tents. This option is useful to restore the archive symbol
124 table after it has been stripped; see strip.
125 -t Write a table of contents of archive to the standard output.
127 Only the files specified by the file operands shall be
128 included in the written list. If no file operands are speci‐
129 fied, all files in archive shall be included in the order of
130 the archive.
131 -T Allow filename truncation of extracted files whose archive
133 names are longer than the file system can support. By
134 default, extracting a file with a name that is too long shall
135 be an error; a diagnostic message shall be written and the
136 file shall not be extracted.
137 -u Update older files in the archive. When used with the -r
139 option, files in the archive shall be replaced only if the
140 corresponding file has a modification time that is at least
141 as new as the modification time of the file in the archive.
142 -v Give verbose output. When used with the option characters -d,
144 -r, or -x, write a detailed file-by-file description of the
145 archive creation and maintenance activity, as described in
146 the STDOUT section.
147 When used with -p, write the name of the file in the archive
149 to the standard output before writing the file in the archive
150 itself to the standard output, as described in the STDOUT
151 section.
152 When used with -t, include a long listing of information
154 about the files in the archive, as described in the STDOUT
155 section.
156 -x Extract the files in the archive named by the file operands
158 from archive. The contents of the archive shall not be
159 changed. If no file operands are given, all files in the ar‐
160 chive shall be extracted. The modification time of each file
161 extracted shall be set to the time the file is extracted from
162 the archive.
163
165 The following operands shall be supported:
166 archive A pathname of the archive.
168 file A pathname. Only the last component shall be used when com‐
170 paring against the names of files in the archive. If two or
171 more file operands have the same last pathname component
172 (basename), the results are unspecified. The implementation's
173 archive format shall not truncate valid filenames of files
174 added to or replaced in the archive.
175 posname The name of a file in the archive, used for relative posi‐
177 tioning; see options -m and -r.
178
180 Not used.
181
183 The archive named by archive shall be a file in the format created by
184 ar -r.
185
187 The following environment variables shall affect the execution of ar:
188 LANG Provide a default value for the internationalization vari‐
190 ables that are unset or null. (See the Base Definitions vol‐
191 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
192 ables for the precedence of internationalization variables
193 used to determine the values of locale categories.)
194 LC_ALL If set to a non-empty string value, override the values of
196 all the other internationalization variables.
197 LC_CTYPE Determine the locale for the interpretation of sequences of
199 bytes of text data as characters (for example, single-byte as
200 opposed to multi-byte characters in arguments and input
201 files).
202 LC_MESSAGES
204 Determine the locale that should be used to affect the format
205 and contents of diagnostic messages written to standard
206 error.
207 LC_TIME Determine the format and content for date and time strings
209 written by ar -tv.
210 NLSPATH Determine the location of message catalogs for the processing
212 of LC_MESSAGES.
213 TMPDIR Determine the pathname that overrides the default directory
215 for temporary files, if any.
216 TZ Determine the timezone used to calculate date and time
218 strings written by ar -tv. If TZ is unset or null, an
219 unspecified default timezone shall be used.
220
222 Default.
223
225 If the -d option is used with the -v option, the standard output format
226 shall be:
227 "d - %s\n", <file>
230 where file is the operand specified on the command line.
232 If the -p option is used with the -v option, ar shall precede the con‐
234 tents of each file with:
235 "\n<%s>\n\n", <file>
238 where file is the operand specified on the command line, if file oper‐
240 ands were specified, and the name of the file in the archive if they
241 were not.
242 If the -r option is used with the -v option:
244 * If file is already in the archive, the standard output format shall
246 be:
247 "r - %s\n", <file>
250 where <file> is the operand specified on the command line.
252 * If file is not already in the archive, the standard output format
254 shall be:
255 "a - %s\n", <file>
258 where <file> is the operand specified on the command line.
260 If the -t option is used, ar shall write the names of the files in the
262 archive to the standard output in the format:
263 "%s\n", <file>
266 where file is the operand specified on the command line, if file oper‐
268 ands were specified, or the name of the file in the archive if they
269 were not.
270 If the -t option is used with the -v option, the standard output format
272 shall be:
273 "%s %u/%u %u %s %d %d:%d %d %s\n", <member mode>, <user ID>,
276 <group ID>, <number of bytes in member>,
277 <abbreviated month>, <day-of-month>, <hour>,
278 <minute>, <year>, <file>
279 where:
281 <file> Shall be the operand specified on the command line, if file
283 operands were specified, or the name of the file in the ar‐
284 chive if they were not.
285 <member mode>
287 Shall be formatted the same as the <file mode> string defined
288 in the STDOUT section of ls, except that the first character,
289 the <entry type>, is not used; the string represents the file
290 mode of the file in the archive at the time it was added to
291 or replaced in the archive.
292 The following represent the last-modification time of a file when it
294 was most recently added to or replaced in the archive:
295 <abbreviated month>
297 Equivalent to the format of the %b conversion specification
298 format in date.
299 <day-of-month>
301 Equivalent to the format of the %e conversion specification
302 format in date.
303 <hour> Equivalent to the format of the %H conversion specification
305 format in date.
306 <minute> Equivalent to the format of the %M conversion specification
308 format in date.
309 <year> Equivalent to the format of the %Y conversion specification
311 format in date.
312 When LC_TIME does not specify the POSIX locale, a different format and
314 order of presentation of these fields relative to each other may be
315 used in a format appropriate in the specified locale.
316 If the -x option is used with the -v option, the standard output format
318 shall be:
319 "x - %s\n", <file>
322 where file is the operand specified on the command line, if file oper‐
324 ands were specified, or the name of the file in the archive if they
325 were not.
326
328 The standard error shall be used only for diagnostic messages. The
329 diagnostic message about creating a new archive when -c is not speci‐
330 fied shall not modify the exit status.
331
333 Archives are files with unspecified formats.
334
336 None.
337
339 The following exit values shall be returned:
340 0 Successful completion.
342 >0 An error occurred.
344
346 Default.
347 The following sections are informative.
349
351 None.
352
354 None.
355
357 The archive format is not described. It is recognized that there are
358 several known ar formats, which are not compatible. The ar utility is
359 included, however, to allow creation of archives that are intended for
360 use only on one machine. The archive is specified as a file, and it can
361 be moved as a file. This does allow an archive to be moved from one
362 machine to another machine that uses the same implementation of ar.
363 Utilities such as pax (and its forebears tar and cpio) also provide
365 portable ``archives''. This is a not a duplication; the ar utility is
366 included to provide an interface primarily for make and the compilers,
367 based on a historical model.
368 In historical implementations, the -q option (available on XSI-conform‐
370 ing systems) is known to execute quickly because ar does not check on
371 whether the added members are already in the archive. This is useful to
372 bypass the searching otherwise done when creating a large archive
373 piece-by-piece. These remarks may but need not remain true for a brand
374 new implementation of this utility; hence, these remarks have been
375 moved into the RATIONALE.
376 BSD implementations historically required applications to provide the
378 -s option whenever the archive was supposed to contain a symbol table.
379 As in this volume of POSIX.1‐2017, System V historically creates or
380 updates an archive symbol table whenever an object file is removed
381 from, added to, or updated in the archive.
382 The OPERANDS section requires what might seem to be true without speci‐
384 fying it: the archive cannot truncate the filenames below {NAME_MAX}.
385 Some historical implementations do so, however, causing unexpected
386 results for the application. Therefore, this volume of POSIX.1‐2017
387 makes the requirement explicit to avoid misunderstandings.
388 According to the System V documentation, the options -dmpqrtx are not
390 required to begin with a <hyphen-minus> ('-'). This volume of
391 POSIX.1‐2017 requires that a conforming application use the leading
392 <hyphen-minus>.
393 The archive format used by the 4.4 BSD implementation is documented in
395 this RATIONALE as an example:
396 A file created by ar begins with the ``magic'' string
398 "!<arch>\n". The rest of the archive is made up of objects,
399 each of which is composed of a header for a file, a possible
400 filename, and the file contents. The header is portable between
401 machine architectures, and, if the file contents are printable,
402 the archive is itself printable.
403 The header is made up of six ASCII fields, followed by a two-
405 character trailer. The fields are the object name (16 charac‐
406 ters), the file last modification time (12 characters), the user
407 and group IDs (each 6 characters), the file mode (8 characters),
408 and the file size (10 characters). All numeric fields are in
409 decimal, except for the file mode, which is in octal.
410 The modification time is the file st_mtime field. The user and
412 group IDs are the file st_uid and st_gid fields. The file mode
413 is the file st_mode field. The file size is the file st_size
414 field. The two-byte trailer is the string "`<newline>".
415 Only the name field has any provision for overflow. If any file‐
417 name is more than 16 characters in length or contains an embed‐
418 ded space, the string "#1/" followed by the ASCII length of the
419 name is written in the name field. The file size (stored in the
420 archive header) is incremented by the length of the name. The
421 name is then written immediately following the archive header.
422 Any unused characters in any of these fields are written as
424 <space> characters. If any fields are their particular maximum
425 number of characters in length, there is no separation between
426 the fields.
427 Objects in the archive are always an even number of bytes long;
429 files that are an odd number of bytes long are padded with a
430 <newline>, although the size in the header does not reflect
431 this.
432 The ar utility description requires that (when all its members are
434 valid object files) ar produce an object code library, which the link‐
435 age editor can use to extract object modules. If the linkage editor
436 needs a symbol table to permit random access to the archive, ar must
437 provide it; however, ar does not require a symbol table.
438 The BSD -o option was omitted. It is a rare conforming application that
440 uses ar to extract object code from a library with concern for its mod‐
441 ification time, since this can only be of importance to make. Hence,
442 since this functionality is not deemed important for applications
443 portability, the modification time of the extracted files is set to the
444 current time.
445 There is at least one known implementation (for a small computer) that
447 can accommodate only object files for that system, disallowing mixed
448 object and other files. The ability to handle any type of file is not
449 only historical practice for most implementations, but is also a rea‐
450 sonable expectation.
451 Consideration was given to changing the output format of ar -tv to the
453 same format as the output of ls -l. This would have made parsing the
454 output of ar the same as that of ls. This was rejected in part because
455 the current ar format is commonly used and changes would break histori‐
456 cal usage. Second, ar gives the user ID and group ID in numeric format
457 separated by a <slash>. Changing this to be the user name and group
458 name would not be correct if the archive were moved to a machine that
459 contained a different user database. Since ar cannot know whether the
460 archive was generated on the same machine, it cannot tell what to
461 report.
462 The text on the -ur option combination is historical practice—since one
464 filename can easily represent two different files (for example, /a/foo
465 and /b/foo), it is reasonable to replace the file in the archive even
466 when the modification time in the archive is identical to that in the
467 file system.
468
470 None.
471
473 c99, date, fort77, pax, strip
474 The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment
476 Variables, Section 12.2, Utility Syntax Guidelines, <unistd.h>,
477 description of {POSIX_NO_TRUNC}
478
480 Portions of this text are reprinted and reproduced in electronic form
481 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
482 table Operating System Interface (POSIX), The Open Group Base Specifi‐
483 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
484 Electrical and Electronics Engineers, Inc and The Open Group. In the
485 event of any discrepancy between this version and the original IEEE and
486 The Open Group Standard, the original IEEE and The Open Group Standard
487 is the referee document. The original Standard can be obtained online
488 at http://www.opengroup.org/unix/online.html .
489 Any typographical or formatting errors that appear in this page are
491 most likely to have been introduced during the conversion of the source
492 files to man page format. To report such errors, see https://www.ker‐
493 nel.org/doc/man-pages/reporting_bugs.html .
494IEEE/The Open Group 2017 AR(1P)