Originální popis anglicky:
ar - create and maintain library archives
Návod, kniha: POSIX Programmer's Manual
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
IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
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. 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
IEEE Std 1003.1-2001, 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:
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:
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:
where <
file> is the operand specified on the command line.
- *
- If file is not already in the archive, the standard
output format shall be:
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:
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:
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 IEEE Std 1003.1-2001, 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 IEEE Std 1003.1-2001
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
IEEE Std 1003.1-2001 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>s. 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 ,
date ,
fort77 ,
pax ,
strip the Base
Definitions volume of IEEE Std 1003.1-2001, Chapter 13, Headers,
<unistd.h> description of {POSIX_NO_TRUNC}
Portions of this text are reprinted and reproduced in electronic form from IEEE
Std 1003.1, 2003 Edition, Standard for Information Technology -- Portable
Operating System Interface (POSIX), The Open Group Base Specifications Issue
6, Copyright (C) 2001-2003 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
.
