ar.1p (20777B)
- '\" et
- .TH AR "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- ar
- \(em create and maintain library archives
- .SH SYNOPSIS
- .LP
- .nf
- ar -d \fB[\fR-v\fB] \fIarchive file\fR...
- .P
- ar -m \fB[\fR-v\fB] \fIarchive file\fR...
- ar -m -a \fB[\fR-v\fB] \fIposname archive file\fR...
- ar -m -b \fB[\fR-v\fB] \fIposname archive file\fR...
- ar -m -i \fB[\fR-v\fB] \fIposname archive file\fR...
- .P
- ar -p \fB[\fR-v\fB] [\fR-s\fB] \fIarchive\fB [\fIfile\fR...\fB]\fR
- .P
- ar -q \fB[\fR-cv\fB] \fIarchive file\fR...
- .P
- ar -r \fB[\fR-cuv\fB] \fIarchive file\fR...
- .P
- ar -r -a \fB[\fR-cuv\fB] \fIposname archive file\fR...
- ar -r -b \fB[\fR-cuv\fB] \fIposname archive file\fR...
- ar -r -i \fB[\fR-cuv\fB] \fIposname archive file\fR...
- .P
- ar -t \fB[\fR-v\fB] [\fR-s\fB] \fIarchive \fB[\fIfile\fR...\fB]\fR
- .P
- ar -x \fB[\fR-v\fB] [\fR-sCT\fB] \fIarchive \fB[\fIfile\fR...\fB]\fR
- .fi
- .SH DESCRIPTION
- .P
- The
- .IR ar
- utility is part of the Software Development Utilities option.
- .P
- The
- .IR ar
- utility can be used to create and maintain groups of files combined
- into an archive. Once an archive has been created, new files can be
- added, and existing files in an archive can be extracted, deleted, or
- replaced. When an archive consists entirely of valid object files, the
- implementation shall format the archive so that it is usable as a
- library for link editing (see
- .IR c99
- and
- .IR fort77 ).
- When some of the archived files are not valid object files, the
- suitability of the archive for library use is undefined.
- If an archive consists entirely of printable files, the entire
- archive shall be printable.
- .P
- When
- .IR ar
- creates an archive, it creates administrative information indicating
- whether a symbol table is present in the archive. When there is at
- least one object file that
- .IR ar
- recognizes as such in the archive, an archive symbol table shall be
- created in the archive and maintained by
- .IR ar ;
- it is used by the link editor to search the archive. Whenever the
- .IR ar
- utility is used to create or update the contents of such an archive,
- the symbol table shall be rebuilt. The
- .BR \-s
- option shall force the symbol table to be rebuilt.
- .P
- All
- .IR file
- operands can be pathnames. However, files within archives shall be
- named by a filename, which is the last component of the pathname used
- when the file was entered into the archive. The comparison of
- .IR file
- operands to the names of files in archives shall be performed by
- comparing the last component of the operand to the name of the file
- in the archive.
- .P
- It is unspecified whether multiple files in the archive may be
- identically named. In the case of such files, however, each
- .IR file
- and
- .IR posname
- operand shall match only the first file in the archive having a name
- that is the same as the last component of the operand.
- .SH OPTIONS
- The
- .IR ar
- utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines",
- except for Guideline 9.
- .P
- The following options shall be supported:
- .IP "\fB\-a\fP" 10
- Position new files in the archive after the file named by the
- .IR posname
- operand.
- .IP "\fB\-b\fP" 10
- Position new files in the archive before the file named by the
- .IR posname
- operand.
- .IP "\fB\-c\fP" 10
- Suppress the diagnostic message that is written to standard error by
- default when the archive
- .IR archive
- is created.
- .IP "\fB\-C\fP" 10
- Prevent extracted files from replacing like-named files in the
- file system. This option is useful when
- .BR \-T
- is also used, to prevent truncated filenames from replacing files with
- the same prefix.
- .IP "\fB\-d\fP" 10
- Delete one or more
- .IR file s
- from
- .IR archive .
- .IP "\fB\-i\fP" 10
- Position new files in the archive before the file in the archive
- named by the
- .IR posname
- operand (equivalent to
- .BR \-b ).
- .IP "\fB\-m\fP" 10
- Move the named files in the archive. The
- .BR \-a ,
- .BR \-b ,
- or
- .BR \-i
- options with the
- .IR posname
- operand indicate the position; otherwise, move the names files in the
- archive to the end of the archive.
- .IP "\fB\-p\fP" 10
- Write the contents of the
- .IR file s
- in the archive named by
- .IR file
- operands from
- .IR archive
- to the standard output. If no
- .IR file
- operands are specified, the contents of all files in the archive shall
- be written in the order of the archive.
- .IP "\fB\-q\fP" 10
- Append the named files to the end of the archive. In this case
- .IR ar
- does not check whether the added files are already in the archive.
- This is useful to bypass the searching otherwise done when creating a
- large archive piece by piece.
- .IP "\fB\-r\fP" 10
- Replace or add
- .IR file s
- to
- .IR archive .
- If the archive named by
- .IR archive
- does not exist, a new archive shall be created and a diagnostic message
- shall be written to standard error (unless the
- .BR \-c
- option is specified). If no
- .IR file s
- are specified and the
- .IR archive
- exists, the results are undefined. Files that replace existing files in
- the archive shall not change the order of the archive. Files that do
- not replace existing files in the archive shall be appended to the
- archive
- unless a
- .BR \-a ,
- .BR \-b ,
- or
- .BR \-i
- option specifies another position.
- .IP "\fB\-s\fP" 10
- Force the regeneration of the archive symbol table even if
- .IR ar
- is not invoked with an option that modifies the archive contents. This
- option is useful to restore the archive symbol table after it has been
- stripped; see
- .IR strip .
- .IP "\fB\-t\fP" 10
- Write a table of contents of
- .IR archive
- to the standard output. Only the files specified by the
- .IR file
- operands shall be included in the written list. If no
- .IR file
- operands are specified, all files in
- .IR archive
- shall be included in the order of the archive.
- .IP "\fB\-T\fP" 10
- Allow filename truncation of extracted files whose archive names are
- longer than the file system can support. By default, extracting a file
- with a name that is too long shall be an error; a diagnostic message
- shall be written and the file shall not be extracted.
- .IP "\fB\-u\fP" 10
- Update older files in the archive. When used with the
- .BR \-r
- option, files in the archive shall be replaced only if the
- corresponding
- .IR file
- has a modification time that is at least as new as the modification
- time of the file in the archive.
- .IP "\fB\-v\fP" 10
- Give verbose output. When used with the option characters
- .BR \-d ,
- .BR \-r ,
- or
- .BR \-x ,
- write a detailed file-by-file description of the archive creation and
- maintenance activity, as described in the STDOUT section.
- .RS 10
- .P
- When used with
- .BR \-p ,
- write the name of the file in the archive to the standard output before
- writing the file in the archive itself to the standard output, as
- described in the STDOUT section.
- .P
- When used with
- .BR \-t ,
- include a long listing of information about the files in the archive,
- as described in the STDOUT section.
- .RE
- .IP "\fB\-x\fP" 10
- Extract the files in the archive named by the
- .IR file
- operands from
- .IR archive .
- The contents of the archive shall not be changed. If no
- .IR file
- operands are given, all files in the archive shall be extracted. The
- modification time of each file extracted shall be set to the time the
- file is extracted from the archive.
- .SH OPERANDS
- The following operands shall be supported:
- .IP "\fIarchive\fR" 10
- A pathname of the archive.
- .IP "\fIfile\fR" 10
- A pathname. Only the last component shall be used when comparing
- against the names of files in the archive. If two or more
- .IR file
- operands have the same last pathname component (basename), the results
- are unspecified. The implementation's archive format shall not truncate
- valid filenames of files added to or replaced in the archive.
- .IP "\fIposname\fR" 10
- The name of a file in the archive, used for relative positioning; see
- options
- .BR \-m
- and
- .BR \-r .
- .SH STDIN
- Not used.
- .SH "INPUT FILES"
- The archive named by
- .IR archive
- shall be a file in the format created by
- .IR ar
- .BR \-r .
- .SH "ENVIRONMENT VARIABLES"
- The following environment variables shall affect the execution of
- .IR ar :
- .IP "\fILANG\fP" 10
- Provide a default value for the internationalization variables that are
- unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 8.2" ", " "Internationalization Variables"
- for the precedence of internationalization variables used to determine
- the values of locale categories.)
- .IP "\fILC_ALL\fP" 10
- If set to a non-empty string value, override the values of all the
- other internationalization variables.
- .IP "\fILC_CTYPE\fP" 10
- Determine the locale for the interpretation of sequences of bytes of
- text data as characters (for example, single-byte as opposed to
- multi-byte characters in arguments and input files).
- .IP "\fILC_MESSAGES\fP" 10
- .br
- Determine the locale that should be used to affect the format and
- contents of diagnostic messages written to standard error.
- .IP "\fILC_TIME\fP" 10
- Determine the format and content for date and time strings written by
- .IR ar
- .BR \-tv .
- .IP "\fINLSPATH\fP" 10
- Determine the location of message catalogs for the processing of
- .IR LC_MESSAGES .
- .IP "\fITMPDIR\fP" 10
- Determine the pathname that overrides the default directory for
- temporary files, if any.
- .IP "\fITZ\fP" 10
- Determine the timezone used to calculate date and time strings written
- by
- .IR ar
- .BR \-tv .
- If
- .IR TZ
- is unset or null, an unspecified default timezone shall be used.
- .SH "ASYNCHRONOUS EVENTS"
- Default.
- .SH STDOUT
- If the
- .BR \-d
- option is used with the
- .BR \-v
- option, the standard output format shall be:
- .sp
- .RS 4
- .nf
- "d - %s\en", <\fIfile\fR>
- .fi
- .P
- .RE
- .P
- where
- .IR file
- is the operand specified on the command line.
- .P
- If the
- .BR \-p
- option is used with the
- .BR \-v
- option,
- .IR ar
- shall precede the contents of each file with:
- .sp
- .RS 4
- .nf
- "\en<%s>\en\en", <\fIfile\fR>
- .fi
- .P
- .RE
- .P
- where
- .IR file
- is the operand specified on the command line, if
- .IR file
- operands were specified, and the name of the file in the archive if
- they were not.
- .P
- If the
- .BR \-r
- option is used with the
- .BR \-v
- option:
- .IP " *" 4
- If
- .IR file
- is already in the archive, the standard output format shall be:
- .RS 4
- .sp
- .RS 4
- .nf
- "r - %s\en", <\fIfile\fR>
- .fi
- .P
- .RE
- .P
- where <\fIfile\fP> is the operand specified on the command line.
- .RE
- .IP " *" 4
- If
- .IR file
- is not already in the archive, the standard output format shall be:
- .RS 4
- .sp
- .RS 4
- .nf
- "a - %s\en", <\fIfile\fR>
- .fi
- .P
- .RE
- .P
- where <\fIfile\fP> is the operand specified on the command line.
- .RE
- .P
- If the
- .BR \-t
- option is used,
- .IR ar
- shall write the names of the files in the archive to the standard
- output in the format:
- .sp
- .RS 4
- .nf
- "%s\en", <\fIfile\fR>
- .fi
- .P
- .RE
- .P
- where
- .IR file
- is the operand specified on the command line, if
- .IR file
- operands were specified, or the name of the file in the archive if they
- were not.
- .P
- If the
- .BR \-t
- option is used with the
- .BR \-v
- option, the standard output format shall be:
- .sp
- .RS 4
- .nf
- "%s %u/%u %u %s %d %d:%d %d %s\en", <\fImember mode\fR>, <\fIuser ID\fR>,
- <\fIgroup ID\fR>, <\fInumber of bytes in member\fR>,
- <\fIabbreviated month\fR>, <\fIday-of-month\fR>, <\fIhour\fR>,
- <\fIminute\fR>, <\fIyear\fR>, <\fIfile\fR>
- .fi
- .P
- .RE
- .P
- where:
- .IP "<\fIfile\fR>" 10
- Shall be the operand specified on the command line, if
- .IR file
- operands were specified, or the name of the file in the archive if they
- were not.
- .IP "<\fImember\ mode\fR>" 10
- .br
- Shall be formatted the same as the <\fIfile\ mode\fR> string defined in
- the STDOUT section of
- .IR ls ,
- except that the first character, the <\fIentry\ type\fR>, is not used;
- the string represents the file mode of the file in the archive at the
- time it was added to or replaced in the archive.
- .br
- .P
- The following represent the last-modification time of a file when it
- was most recently added to or replaced in the archive:
- .IP "<\fIabbreviated\ month\fR>" 10
- .br
- Equivalent to the format of the
- .BR %b
- conversion specification format in
- .IR date .
- .IP "<\fIday-of-month\fR>" 10
- .br
- Equivalent to the format of the
- .BR %e
- conversion specification format in
- .IR date .
- .IP "<\fIhour\fR>" 10
- Equivalent to the format of the
- .BR %H
- conversion specification format in
- .IR date .
- .IP "<\fIminute\fR>" 10
- Equivalent to the format of the
- .BR %M
- conversion specification format in
- .IR date .
- .IP "<\fIyear\fR>" 10
- Equivalent to the format of the
- .BR %Y
- conversion specification format in
- .IR date .
- .P
- When
- .IR LC_TIME
- does not specify the POSIX locale, a different format and order of
- presentation of these fields relative to each other may be used in a
- format appropriate in the specified locale.
- .P
- If the
- .BR \-x
- option is used with the
- .BR \-v
- option, the standard output format shall be:
- .sp
- .RS 4
- .nf
- "x - %s\en", <\fIfile\fR>
- .fi
- .P
- .RE
- .P
- where
- .IR file
- is the operand specified on the command line, if
- .IR file
- operands were specified, or the name of the file in the archive if they
- were not.
- .SH STDERR
- The standard error shall be used only for diagnostic messages.
- The diagnostic message about creating a new archive when
- .BR \-c
- is not specified shall not modify the exit status.
- .SH "OUTPUT FILES"
- Archives are files with unspecified formats.
- .SH "EXTENDED DESCRIPTION"
- None.
- .SH "EXIT STATUS"
- The following exit values shall be returned:
- .IP "\00" 6
- Successful completion.
- .IP >0 6
- An error occurred.
- .SH "CONSEQUENCES OF ERRORS"
- Default.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- None.
- .SH EXAMPLES
- None.
- .SH RATIONALE
- The archive format is not described. It is recognized that there are
- several known
- .IR ar
- formats, which are not compatible. The
- .IR ar
- utility is included, however, to allow creation of archives that
- are intended for use only on one machine. The archive is
- specified as a file, and it can be moved as a file. This does allow an
- archive to be moved from one machine to another machine that uses the
- same implementation of
- .IR ar .
- .P
- Utilities such as
- .IR pax
- (and its forebears
- .IR tar
- and
- .IR cpio )
- also provide portable ``archives''. This is a not a duplication; the
- .IR ar
- utility is included to provide an interface primarily for
- .IR make
- and the compilers, based on a historical model.
- .P
- In historical implementations, the
- .BR \-q
- option (available on XSI-conforming systems) is known to execute
- quickly because
- .IR ar
- does not check on whether the added members are already in the
- archive. This is useful to bypass the searching otherwise done when
- creating a large archive piece-by-piece. These remarks may but need not
- remain true for a brand new implementation of this utility; hence,
- these remarks have been moved into the RATIONALE.
- .P
- BSD implementations historically required applications to provide the
- .BR \-s
- option whenever the archive was supposed to contain a symbol table.
- As in this volume of POSIX.1\(hy2017, System V historically creates or updates an archive symbol
- table whenever an object file is removed from, added to, or updated
- in the archive.
- .P
- The OPERANDS section requires what might seem to be true without
- specifying it: the archive cannot truncate the filenames below
- {NAME_MAX}.
- Some historical implementations do so, however, causing unexpected
- results for the application. Therefore, this volume of POSIX.1\(hy2017 makes the requirement
- explicit to avoid misunderstandings.
- .P
- According to the System V documentation, the options
- .BR \-dmpqrtx
- are not required to begin with a
- <hyphen-minus>
- (\c
- .BR '\-' ).
- This volume of POSIX.1\(hy2017 requires that a conforming application use the leading
- <hyphen-minus>.
- .P
- The archive format used by the 4.4 BSD implementation is documented in
- this RATIONALE as an example:
- .sp
- .RS
- A file created by
- .IR ar
- begins with the ``magic'' string
- .BR \(dq!<arch>\en\(dq .
- The rest of the archive is made up of objects, each of which is
- composed of a header for a file, a possible filename, and the file
- contents. The header is portable between machine architectures, and, if
- the file contents are printable, the archive is itself printable.
- .P
- The header is made up of six ASCII fields, followed by a two-character
- trailer. The fields are the object name (16 characters), the file last
- modification time (12 characters), the user and group IDs (each 6
- characters), the file mode (8 characters), and the file size (10
- characters). All numeric fields are in decimal, except for the file
- mode, which is in octal.
- .P
- The modification time is the file
- .IR st_mtime
- field. The user and group IDs are the file
- .IR st_uid
- and
- .IR st_gid
- fields. The file mode is the file
- .IR st_mode
- field. The file size is the file
- .IR st_size
- field. The two-byte trailer is the string
- .BR \(dq`<newline>\(dq .
- .P
- Only the name field has any provision for overflow. If any filename is
- more than 16 characters in length or contains an embedded space, the
- string
- .BR \(dq#1/\(dq
- followed by the ASCII length of the name is written in the name field.
- The file size (stored in the archive header) is incremented by the
- length of the name. The name is then written immediately following the
- archive header.
- .P
- Any unused characters in any of these fields are written as
- <space>
- characters. If any fields are their particular maximum number of
- characters in length, there is no separation between the fields.
- .P
- Objects in the archive are always an even number of bytes long; files
- that are an odd number of bytes long are padded with a
- <newline>,
- although the size in the header does not reflect this.
- .RE
- .P
- The
- .IR ar
- utility description requires that (when all its members are valid
- object files)
- .IR ar
- produce an object code library, which the linkage editor can use to
- extract object modules. If the linkage editor needs a symbol table to
- permit random access to the archive,
- .IR ar
- must provide it; however,
- .IR ar
- does not require a symbol table.
- .P
- The BSD
- .BR \-o
- option was omitted. It is a rare conforming application that uses
- .IR ar
- to extract object code from a library with concern for its modification
- time, since this can only be of importance to
- .IR make .
- Hence, since this functionality is not deemed important for
- applications portability, the modification time of the extracted files
- is set to the current time.
- .P
- There is at least one known implementation (for a small computer) that
- can accommodate only object files for that system, disallowing mixed
- object and other files. The ability to handle any type of file is not
- only historical practice for most implementations, but is also a
- reasonable expectation.
- .P
- Consideration was given to changing the output format of
- .IR ar
- .BR \-tv
- to the same format as the output of
- .IR ls
- .BR \-l .
- This would have made parsing the output of
- .IR ar
- the same as that of
- .IR ls .
- This was rejected in part because the current
- .IR ar
- format is commonly used and changes would break historical usage.
- Second,
- .IR ar
- gives the user ID and group ID in numeric format separated by a
- <slash>.
- Changing this to be the user name and group name would not be correct
- if the archive were moved to a machine that contained a different user
- database. Since
- .IR ar
- cannot know whether the archive was generated on the same machine,
- it cannot tell what to report.
- .P
- The text on the
- .BR \-ur
- option combination is historical practice\(emsince one filename can
- easily represent two different files (for example,
- .BR /a/foo
- and
- .BR /b/foo ),
- it is reasonable to replace the file in the archive even when the
- modification time in the archive is identical to that in the file
- system.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIc99\fR\^",
- .IR "\fIdate\fR\^",
- .IR "\fIfort77\fR\^",
- .IR "\fIpax\fR\^",
- .IR "\fIstrip\fR\^"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables",
- .IR "Section 12.2" ", " "Utility Syntax Guidelines",
- .IR "\fB<unistd.h>\fP",
- description of
- {POSIX_NO_TRUNC}
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .