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

NAME

12       ar — create and maintain library archives
13

SYNOPSIS

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

DESCRIPTION

37       The ar utility is part of the Software Development Utilities option.
38
39       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
49       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
58       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
65       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

OPTIONS

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
75       The following options shall be supported:
76
77       -a        Position new files in the archive after the file named by the
78                 posname operand.
79
80       -b        Position new files in the archive before the  file  named  by
81                 the posname operand.
82
83       -c        Suppress  the  diagnostic message that is written to standard
84                 error by default when the archive archive is created.
85
86       -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
91       -d        Delete one or more files from archive.
92
93       -i        Position  new files in the archive before the file in the ar‐
94                 chive named by the posname operand (equivalent to -b).
95
96       -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
101       -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
106       -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
111       -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
121       -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
126       -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
132       -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
138       -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
143       -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
148                 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
153                 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
157       -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

OPERANDS

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

STDIN

180       Not used.
181

INPUT FILES

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

ENVIRONMENT VARIABLES

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

ASYNCHRONOUS EVENTS

222       Default.
223

STDOUT

225       If the -d option is used with the -v option, the standard output format
226       shall be:
227
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
237           "\n<%s>\n\n", <file>
238
239       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
243       If the -r option is used with the -v option:
244
245        *  If file is already in the archive, the standard output format shall
246           be:
247
248
249               "r - %s\n", <file>
250
251           where <file> is the operand specified on the command line.
252
253        *  If  file  is not already in the archive, the standard output format
254           shall be:
255
256
257               "a - %s\n", <file>
258
259           where <file> is the operand specified on the command line.
260
261       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
264
265           "%s\n", <file>
266
267       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
271       If the -t option is used with the -v option, the standard output format
272       shall be:
273
274
275           "%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
280       where:
281
282       <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
286       <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
293       The following represent the last-modification time of a  file  when  it
294       was most recently added to or replaced in the archive:
295
296       <abbreviated month>
297                 Equivalent  to  the format of the %b conversion specification
298                 format in date.
299
300       <day-of-month>
301                 Equivalent to the format of the %e  conversion  specification
302                 format in date.
303
304       <hour>    Equivalent  to  the format of the %H conversion specification
305                 format in date.
306
307       <minute>  Equivalent to the format of the %M  conversion  specification
308                 format in date.
309
310       <year>    Equivalent  to  the format of the %Y conversion specification
311                 format in date.
312
313       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
317       If the -x option is used with the -v option, the standard output format
318       shall be:
319
320
321           "x - %s\n", <file>
322
323       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

STDERR

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

OUTPUT FILES

333       Archives are files with unspecified formats.
334

EXTENDED DESCRIPTION

336       None.
337

EXIT STATUS

339       The following exit values shall be returned:
340
341        0    Successful completion.
342
343       >0    An error occurred.
344

CONSEQUENCES OF ERRORS

346       Default.
347
348       The following sections are informative.
349

APPLICATION USAGE

351       None.
352

EXAMPLES

354       None.
355

RATIONALE

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
364       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
369       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
377       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
383       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
389       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
394       The archive format used by the 4.4 BSD implementation is documented  in
395       this RATIONALE as an example:
396
397              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
404              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
411              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
416              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
423              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
428              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
433       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
439       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
446       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
452       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
463       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

FUTURE DIRECTIONS

470       None.
471

SEE ALSO

473       c99, date, fort77, pax, strip
474
475       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
490       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 .
494
495
496
497IEEE/The Open Group                  2017                               AR(1P)
Impressum