1AR(1P)                     POSIX Programmer's Manual                    AR(1P)
2
3
4

PROLOG

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
11

NAME

13       ar — create and maintain library archives
14

SYNOPSIS

16       ar −d [−v] archive file...
17
18       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
23       ar −p [−v] [−s] archive [file...]
24
25       ar −q [−cv] archive file...
26
27       ar −r [−cuv] archive file...
28
29       ar −r −a [−cuv] posname archive file...
30       ar −r −b [−cuv] posname archive file...
31       ar −r −i [−cuv] posname archive file...
32
33       ar −t [−v] [−s] archive [file...]
34
35       ar −x [−v] [−sCT] archive [file...]
36

DESCRIPTION

38       The ar utility is part of the Software Development Utilities option.
39
40       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
50       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
59       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
66       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

OPTIONS

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
76       The following options shall be supported:
77
78       −a        Position new files in the archive after the file named by the
79                 posname operand.
80
81       −b        Position new files in the archive before the  file  named  by
82                 the posname operand.
83
84       −c        Suppress  the  diagnostic message that is written to standard
85                 error by default when the archive archive is created.
86
87       −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
92       −d        Delete one or more files from archive.
93
94       −i        Position  new files in the archive before the file in the ar‐
95                 chive named by the posname operand (equivalent to −b).
96
97       −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
102       −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
107       −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
112       −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
122       −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
127       −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
133       −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
139       −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
144       −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
149                 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
154                 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
158       −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

OPERANDS

166       The following operands shall be supported:
167
168       archive   A pathname of the archive.
169
170       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
177       posname   The  name  of  a file in the archive, used for relative posi‐
178                 tioning; see options −m and −r.
179

STDIN

181       Not used.
182

INPUT FILES

184       The archive named by archive shall be a file in the format  created  by
185       ar −r.
186

ENVIRONMENT VARIABLES

188       The following environment variables shall affect the execution of ar:
189
190       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
196       LC_ALL    If  set  to  a non-empty string value, override the values of
197                 all the other internationalization variables.
198
199       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
204       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
209       LC_TIME   Determine  the  format  and content for date and time strings
210                 written by ar −tv.
211
212       NLSPATH   Determine the location of message catalogs for the processing
213                 of LC_MESSAGES.
214
215       TMPDIR    Determine  the  pathname that overrides the default directory
216                 for temporary files, if any.
217
218       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

ASYNCHRONOUS EVENTS

223       Default.
224

STDOUT

226       If the −d option is used with the −v option, the standard output format
227       shall be:
228
229           "d − %s\n", <file>
230
231       where file is the operand specified on the command line.
232
233       If  the −p option is used with the −v option, ar shall precede the con‐
234       tents of each file with:
235
236           "\n<%s>\n\n", <file>
237
238       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
242       If the −r option is used with the −v option:
243
244        *  If file is already in the archive, the standard output format shall
245           be:
246
247               "r − %s\n", <file>
248
249           where <file> is the operand specified on the command line.
250
251        *  If  file  is not already in the archive, the standard output format
252           shall be:
253
254               "a − %s\n", <file>
255
256           where <file> is the operand specified on the command line.
257
258       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
261           "%s\n", <file>
262
263       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
267       If the −t option is used with the −v option, the standard output format
268       shall be:
269
270           "%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
275       where:
276
277       <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
281       <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
288       The following represent the last-modification time of a  file  when  it
289       was most recently added to or replaced in the archive:
290
291       <abbreviated month>
292                 Equivalent  to  the format of the %b conversion specification
293                 format in date.
294
295       <day-of-month>
296                 Equivalent to the format of the %e  conversion  specification
297                 format in date.
298
299       <hour>    Equivalent  to  the format of the %H conversion specification
300                 format in date.
301
302       <minute>  Equivalent to the format of the %M  conversion  specification
303                 format in date.
304
305       <year>    Equivalent  to  the format of the %Y conversion specification
306                 format in date.
307
308       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
312       If the −x option is used with the −v option, the standard output format
313       shall be:
314
315           "x − %s\n", <file>
316
317       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

STDERR

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

OUTPUT FILES

327       Archives are files with unspecified formats.
328

EXTENDED DESCRIPTION

330       None.
331

EXIT STATUS

333       The following exit values shall be returned:
334
335        0    Successful completion.
336
337       >0    An error occurred.
338

CONSEQUENCES OF ERRORS

340       Default.
341
342       The following sections are informative.
343

APPLICATION USAGE

345       None.
346

EXAMPLES

348       None.
349

RATIONALE

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
358       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
363       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
371       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
377       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
383       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
387       The  archive format used by the 4.4 BSD implementation is documented in
388       this RATIONALE as an example:
389
390              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
397              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
404              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
409              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
416              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
421              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
426       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
432       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
439       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
445       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
456       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

FUTURE DIRECTIONS

463       None.
464

SEE ALSO

466       c99, date, fort77, pax, strip
467
468       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
484       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 .
488
489
490
491IEEE/The Open Group                  2013                               AR(1P)
Impressum