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