|
PROLOG | NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | STDIN | INPUT FILES | ENVIRONMENT VARIABLES | ASYNCHRONOUS EVENTS | STDOUT | STDERR | OUTPUT FILES | EXTENDED DESCRIPTION | EXIT STATUS | CONSEQUENCES OF ERRORS | APPLICATION USAGE | EXAMPLES | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT |
AR(1P) POSIX Programmer's Manual AR(1P)
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.
ar — create and maintain library archives
ar −d [−v] archive file...
ar −m [−v] archive file...
ar −m −a [−v] posname archive file...
ar −m −b [−v] posname archive file...
ar −m −i [−v] posname archive file...
ar −p [−v] [−s] archive [file...]
ar −q [−cv] archive file...
ar −r [−cuv] archive file...
ar −r −a [−cuv] posname archive file...
ar −r −b [−cuv] posname archive file...
ar −r −i [−cuv] posname archive file...
ar −t [−v] [−s] archive [file...]
ar −x [−v] [−sCT] archive [file...]
The ar utility is part of the Software Development Utilities option.
The 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 c99 and 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.
When 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 ar recognizes as such in the
archive, an archive symbol table shall be created in the archive and
maintained by ar; it is used by the link editor to search the
archive. Whenever the ar utility is used to create or update the
contents of such an archive, the symbol table shall be rebuilt. The
−s option shall force the symbol table to be rebuilt.
All 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 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.
It is unspecified whether multiple files in the archive may be
identically named. In the case of such files, however, each file and
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.
The ar utility shall conform to the Base Definitions volume of
POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines, except for
Guideline 9.
The following options shall be supported:
−a Position new files in the archive after the file named by
the posname operand.
−b Position new files in the archive before the file named by
the posname operand.
−c Suppress the diagnostic message that is written to standard
error by default when the archive archive is created.
−C Prevent extracted files from replacing like-named files in
the file system. This option is useful when −T is also
used, to prevent truncated filenames from replacing files
with the same prefix.
−d Delete one or more files from archive.
−i Position new files in the archive before the file in the
archive named by the posname operand (equivalent to −b).
−m Move the named files in the archive. The −a, −b, or −i
options with the posname operand indicate the position;
otherwise, move the names files in the archive to the end
of the archive.
−p Write the contents of the files in the archive named by
file operands from archive to the standard output. If no
file operands are specified, the contents of all files in
the archive shall be written in the order of the archive.
−q Append the named files to the end of the archive. In this
case 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.
−r Replace or add files to archive. If the archive named by
archive does not exist, a new archive shall be created and
a diagnostic message shall be written to standard error
(unless the −c option is specified). If no files are
specified and the 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 −a, −b, or −i option specifies
another position.
−s Force the regeneration of the archive symbol table even if
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 strip.
−t Write a table of contents of archive to the standard
output. Only the files specified by the file operands shall
be included in the written list. If no file operands are
specified, all files in archive shall be included in the
order of the archive.
−T 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.
−u Update older files in the archive. When used with the −r
option, files in the archive shall be replaced only if the
corresponding file has a modification time that is at least
as new as the modification time of the file in the archive.
−v Give verbose output. When used with the option characters
−d, −r, or −x, write a detailed file-by-file description of
the archive creation and maintenance activity, as described
in the STDOUT section.
When used with −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.
When used with −t, include a long listing of information
about the files in the archive, as described in the STDOUT
section.
−x Extract the files in the archive named by the file operands
from archive. The contents of the archive shall not be
changed. If no 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.
The following operands shall be supported:
archive A pathname of the archive.
file A pathname. Only the last component shall be used when
comparing against the names of files in the archive. If two
or more 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.
posname The name of a file in the archive, used for relative
positioning; see options −m and −r.
Not used.
The archive named by archive shall be a file in the format created by
ar −r.
The following environment variables shall affect the execution of ar:
LANG Provide a default value for the internationalization
variables that are unset or null. (See the Base Definitions
volume of POSIX.1‐2008, Section 8.2, Internationalization
Variables for the precedence of internationalization
variables used to determine the values of locale
categories.)
LC_ALL If set to a non-empty string value, override the values of
all the other internationalization variables.
LC_CTYPE 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).
LC_MESSAGES
Determine the locale that should be used to affect the
format and contents of diagnostic messages written to
standard error.
LC_TIME Determine the format and content for date and time strings
written by ar −tv.
NLSPATH Determine the location of message catalogs for the
processing of LC_MESSAGES.
TMPDIR Determine the pathname that overrides the default directory
for temporary files, if any.
TZ Determine the timezone used to calculate date and time
strings written by ar −tv. If TZ is unset or null, an
unspecified default timezone shall be used.
Default.
If the −d option is used with the −v option, the standard output
format shall be:
"d − %s\n", <file>
where file is the operand specified on the command line.
If the −p option is used with the −v option, ar shall precede the
contents of each file with:
"\n<%s>\n\n", <file>
where file is the operand specified on the command line, if file
operands were specified, and the name of the file in the archive if
they were not.
If the −r option is used with the −v option:
* If file is already in the archive, the standard output format
shall be:
"r − %s\n", <file>
where <file> is the operand specified on the command line.
* If file is not already in the archive, the standard output format
shall be:
"a − %s\n", <file>
where <file> is the operand specified on the command line.
If the −t option is used, ar shall write the names of the files in
the archive to the standard output in the format:
"%s\n", <file>
where file is the operand specified on the command line, if file
operands were specified, or the name of the file in the archive if
they were not.
If the −t option is used with the −v option, the standard output
format shall be:
"%s %u/%u %u %s %d %d:%d %d %s\n", <member mode>, <user ID>,
<group ID>, <number of bytes in member>,
<abbreviated month>, <day-of-month>, <hour>,
<minute>, <year>, <file>
where:
<file> Shall be the operand specified on the command line, if file
operands were specified, or the name of the file in the
archive if they were not.
<member mode>
Shall be formatted the same as the <file mode> string
defined in the STDOUT section of ls, except that the first
character, the <entry type>, 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.
The following represent the last-modification time of a file when it
was most recently added to or replaced in the archive:
<abbreviated month>
Equivalent to the format of the %b conversion specification
format in date.
<day-of-month>
Equivalent to the format of the %e conversion specification
format in date.
<hour> Equivalent to the format of the %H conversion specification
format in date.
<minute> Equivalent to the format of the %M conversion specification
format in date.
<year> Equivalent to the format of the %Y conversion specification
format in date.
When 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.
If the −x option is used with the −v option, the standard output
format shall be:
"x − %s\n", <file>
where file is the operand specified on the command line, if file
operands were specified, or the name of the file in the archive if
they were not.
The standard error shall be used only for diagnostic messages. The
diagnostic message about creating a new archive when −c is not
specified shall not modify the exit status.
Archives are files with unspecified formats.
None.
The following exit values shall be returned:
0 Successful completion.
>0 An error occurred.
Default.
The following sections are informative.
None.
None.
The archive format is not described. It is recognized that there are
several known ar formats, which are not compatible. The 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 ar.
Utilities such as pax (and its forebears tar and cpio) also provide
portable ``archives''. This is a not a duplication; the ar utility is
included to provide an interface primarily for make and the
compilers, based on a historical model.
In historical implementations, the −q option (available on XSI-
conforming systems) is known to execute quickly because 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.
BSD implementations historically required applications to provide the
−s option whenever the archive was supposed to contain a symbol
table. As in this volume of POSIX.1‐2008, System V historically
creates or updates an archive symbol table whenever an object file is
removed from, added to, or updated in the archive.
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‐2008 makes the requirement explicit to avoid
misunderstandings.
According to the System V documentation, the options −dmpqrtx are not
required to begin with a <hyphen> ('−'). This volume of POSIX.1‐2008
requires that a conforming application use the leading <hyphen>.
The archive format used by the 4.4 BSD implementation is documented
in this RATIONALE as an example:
A file created by ar begins with the ``magic'' string
"!<arch>\n". 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.
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.
The modification time is the file st_mtime field. The user and
group IDs are the file st_uid and st_gid fields. The file mode
is the file st_mode field. The file size is the file st_size
field. The two-byte trailer is the string "`<newline>".
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 "#1/" 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.
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.
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.
The ar utility description requires that (when all its members are
valid object files) 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,
ar must provide it; however, ar does not require a symbol table.
The BSD −o option was omitted. It is a rare conforming application
that uses ar to extract object code from a library with concern for
its modification time, since this can only be of importance to 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.
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.
Consideration was given to changing the output format of ar −tv to
the same format as the output of ls −l. This would have made parsing
the output of ar the same as that of ls. This was rejected in part
because the current ar format is commonly used and changes would
break historical usage. Second, 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 ar cannot
know whether the archive was generated on the same machine, it cannot
tell what to report.
The text on the −ur option combination is historical practice—since
one filename can easily represent two different files (for example,
/a/foo and /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.
None.
c99(1p), date(1p), fort77(1p), pax(1p), strip(1p)
The Base Definitions volume of POSIX.1‐2008, Chapter 8, Environment
Variables, Section 12.2, Utility Syntax Guidelines, unistd.h(0p),
description of {POSIX_NO_TRUNC}
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2013 Edition, Standard for Information
Technology -- Portable Operating System Interface (POSIX), The Open
Group Base Specifications Issue 7, Copyright (C) 2013 by the
Institute of Electrical and Electronics Engineers, Inc and The Open
Group. (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1
applied.) 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.unix.org/online.html .
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 .
IEEE/The Open Group 2013 AR(1P)
Pages that refer to this page: c99(1p), file(1p), fort77(1p), make(1p), nm(1p), strip(1p)