Import of man-pages 1.70

[thirdparty/man-pages.git] / man1p / ar.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "AR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" ar 
.SH NAME
ar \- create and maintain library archives
.SH SYNOPSIS
.LP
\fBar -d\fP\fB[\fP\fB-v\fP\fB]\fP \fIarchive file\fP \fB... \fP
\fB
.br
.sp
\fP
.LP
\fBar -m\fP \fB[\fP\fB-v\fP\fB]\fP \fIarchive file\fP \fB...
.br
.sp
ar -m -a\fP\fB[\fP\fB-v\fP\fB]\fP \fIposname archive file\fP \fB...
.br
.sp
ar -m -b\fP\fB[\fP\fB-v\fP\fB]\fP \fIposname archive file\fP \fB...
.br
.sp
ar -m -i\fP\fB[\fP\fB-v\fP\fB]\fP \fIposname archive file\fP \fB...
\fP
\fB
.br
.sp
ar -p\fP\fB[\fP\fB-v\fP\fB][\fP\fB-s\fP\fB]\fP\fIarchive\fP \fB[\fP\fIfile\fP
\fB\&...\fP\fB]\fP\fB
.br
.sp
\fP
.LP
\fBar -q\fP\fB[\fP\fB-cv\fP\fB]\fP \fIarchive file\fP \fB... \fP
\fB
.br
.sp
ar -r\fP\fB[\fP\fB-cuv\fP\fB]\fP \fIarchive file\fP \fB...
.br
.sp
\fP
.LP
\fBar -r -a\fP\fB[\fP\fB-cuv\fP\fB]\fP \fIposname archive file\fP
\fB\&...
.br
.sp
ar -r -b\fP\fB[\fP\fB-cuv\fP\fB]\fP \fIposname archive file\fP \fB...
.br
.sp
ar -r -i\fP\fB[\fP\fB-cuv\fP\fB]\fP \fIposname archive file\fP \fB...
\fP
\fB
.br
.sp
ar -t\fP\fB[\fP\fB-v\fP\fB][\fP\fB-s\fP\fB]\fP\fIarchive\fP \fB[\fP\fIfile\fP
\fB\&...\fP\fB]\fP\fB
.br
.sp
ar -x\fP\fB[\fP\fB-v\fP\fB][\fP\fB-sCT\fP\fB]\fP\fIarchive\fP \fB[\fP\fIfile\fP
\fB\&...\fP\fB]\fP\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIar\fP utility is part of the Software Development Utilities
option.
.LP
The \fIar\fP 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
\fIc99\fP and \fIfort77\fP). 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.
.LP
When \fIar\fP 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 \fIar\fP recognizes
as such in the archive, an archive symbol table shall be
created in the archive and maintained by \fIar\fP; it is used by the
link editor to search the archive. Whenever the \fIar\fP
utility is used to create or update the contents of such an archive,
the symbol table shall be rebuilt. The \fB-s\fP option shall
force the symbol table to be rebuilt. 
.LP
All \fIfile\fP 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 \fIfile\fP 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.
.LP
It is unspecified whether multiple files in the archive may be identically
named. In the case of such files, however, each
\fIfile\fP   \ and \fIposname\fP  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
.LP
The \fIar\fP utility shall conform to the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
.LP
The following options shall be supported:
.TP 7
\fB-a\fP
Position new files in the archive after the file named by the \fIposname\fP
operand. 
.TP 7
\fB-b\fP
Position new files in the archive before the file named by the \fIposname\fP
operand. 
.TP 7
\fB-c\fP
Suppress the diagnostic message that is written to standard error
by default when the archive \fIarchive\fP is created.
.TP 7
\fB-C\fP
Prevent extracted files from replacing like-named files in the file
system. This option is useful when \fB-T\fP is also used, to
prevent truncated filenames from replacing files with the same prefix.
.TP 7
\fB-d\fP
Delete one or more \fIfile\fPs from \fIarchive\fP.
.TP 7
\fB-i\fP
Position new files in the archive before the file in the archive named
by the \fIposname\fP operand (equivalent to \fB-b\fP).
.TP 7
\fB-m\fP
Move the named files in the archive. The \fB-a\fP, \fB-b\fP, or \fB-i\fP
options with the \fIposname\fP operand indicate the
position; otherwise, move the names files in the archive to the end
of the archive. 
.TP 7
\fB-p\fP
Write the contents of the \fIfile\fPs in the archive named by \fIfile\fP
operands from \fIarchive\fP to the standard output.
If no \fIfile\fP operands are specified, the contents of all files
in the archive shall be written in the order of the
archive.
.TP 7
\fB-q\fP
Append the named files to the end of the archive. In this case \fIar\fP
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. 
.TP 7
\fB-r\fP
Replace or add \fIfile\fPs to \fIarchive\fP. If the archive named
by \fIarchive\fP does not exist, a new archive shall be
created and a diagnostic message shall be written to standard error
(unless the \fB-c\fP option is specified). If no \fIfile\fPs
are specified and the \fIarchive\fP 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 \fB-a\fP, \fB-b\fP, or \fB-i\fP option specifies another position.
.TP 7
\fB-s\fP
Force the regeneration of the archive symbol table even if \fIar\fP
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 \fIstrip\fP. 
.TP 7
\fB-t\fP
Write a table of contents of \fIarchive\fP to the standard output.
The files specified by the \fIfile\fP operands shall be
included in the written list. If no \fIfile\fP operands are specified,
all files in \fIarchive\fP shall be included in the order
of the archive.
.TP 7
\fB-T\fP
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. 
.TP 7
\fB-u\fP
Update older files in the archive. When used with the \fB-r\fP option,
files in the archive shall be replaced only if the
corresponding \fIfile\fP has a modification time that is at least
as new as the modification time of the file in the archive.
.TP 7
\fB-v\fP
Give verbose output. When used with the option characters \fB-d\fP,
\fB-r\fP, or \fB-x\fP, write a detailed file-by-file
description of the archive creation and maintenance activity, as described
in the STDOUT section. 
.LP
When used with \fB-p\fP, 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.
.LP
When used with \fB-t\fP, include a long listing of information about
the files in the archive, as described in the STDOUT
section.
.TP 7
\fB-x\fP
Extract the files in the archive named by the \fIfile\fP operands
from \fIarchive\fP. The contents of the archive shall not
be changed. If no \fIfile\fP 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.
.sp
.SH OPERANDS
.LP
The following operands shall be supported:
.TP 7
\fIarchive\fP
A pathname of the archive.
.TP 7
\fIfile\fP
A pathname. Only the last component shall be used when comparing against
the names of files in the archive. If two or more
\fIfile\fP 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.
.TP 7
\fIposname\fP
The name of a file in the archive, used for relative positioning;
see options \fB-m\fP and \fB-r\fP. 
.sp
.SH STDIN
.LP
Not used.
.SH INPUT FILES
.LP
The archive named by \fIarchive\fP shall be a file in the format created
by \fIar\fP \fB-r\fP.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fIar\fP:
.TP 7
\fILANG\fP
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.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_CTYPE\fP
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).
.TP 7
\fILC_MESSAGES\fP
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard
error.
.TP 7
\fILC_TIME\fP
Determine the format and content for date and time strings written
by \fIar\fP \fB-tv\fP.
.TP 7
\fINLSPATH\fP
Determine the location of message catalogs for the processing of \fILC_MESSAGES
\&.\fP 
.TP 7
\fITMPDIR\fP
Determine the pathname that overrides the default directory for temporary
files, if any.
.TP 7
\fITZ\fP
Determine the timezone used to calculate date and time strings written
by \fIar\fP \fB-tv\fP. If \fITZ\fP is unset or null,
an unspecified default timezone shall be used.
.sp
.SH ASYNCHRONOUS EVENTS
.LP
Default.
.SH STDOUT
.LP
If the \fB-d\fP option is used with the \fB-v\fP option, the standard
output format shall be:
.sp
.RS
.nf

\fB"d - %s\\n", <\fP\fIfile\fP\fB>
\fP
.fi
.RE
.LP
where \fIfile\fP is the operand specified on the command line.
.LP
If the \fB-p\fP option is used with the \fB-v\fP option, \fIar\fP
shall precede the contents of each file with:
.sp
.RS
.nf

\fB"\\n<%s>\\n\\n", <\fP\fIfile\fP\fB>
\fP
.fi
.RE
.LP
where \fIfile\fP is the operand specified on the command line, if
\fIfile\fP operands were specified, and the name of the file
in the archive if they were not.
.LP
If the \fB-r\fP option is used with the \fB-v\fP option:
.IP " *" 3
If \fIfile\fP is already in the archive, the standard output format
shall be:
.sp
.RS
.nf

\fB"r - %s\\n", <\fP\fIfile\fP\fB>
\fP
.fi
.RE
.LP
where <\fIfile\fP> is the operand specified on the command line.
.LP
.IP " *" 3
If \fIfile\fP is not already in the archive, the standard output format
shall be:
.sp
.RS
.nf

\fB"a - %s\\n", <\fP\fIfile\fP\fB>
\fP
.fi
.RE
.LP
where <\fIfile\fP> is the operand specified on the command line.
.LP
.LP
If the \fB-t\fP option is used, \fIar\fP shall write the names of
the files in the archive to the standard output in the
format:
.sp
.RS
.nf

\fB"%s\\n", <\fP\fIfile\fP\fB>
\fP
.fi
.RE
.LP
where \fIfile\fP is the operand specified on the command line, if
\fIfile\fP operands were specified, or the name of the file
in the archive if they were not.
.LP
If the \fB-t\fP option is used with the \fB-v\fP option, the standard
output format shall be:
.sp
.RS
.nf

\fB"%s %u/%u %u %s %d %d:%d %d %s\\n", <\fP\fImember mode\fP\fB>, <\fP\fIuser ID\fP\fB>,
    <\fP\fIgroup ID\fP\fB>, <\fP\fInumber of bytes in member\fP\fB>,
    <\fP\fIabbreviated month\fP\fB>, <\fP\fIday-of-month\fP\fB>, <\fP\fIhour\fP\fB>,
    <\fP\fIminute\fP\fB>, <\fP\fIyear\fP\fB>, <\fP\fIfile\fP\fB>
\fP
.fi
.RE
.LP
where:
.TP 7
<\fIfile\fP>
Shall be the operand specified on the command line, if \fIfile\fP
operands were specified, or the name of the file in the
archive if they were not.
.TP 7
<\fImember\ mode\fP>
.sp
Shall be formatted the same as the <\fIfile\ mode\fP> string defined
in the STDOUT section of \fIls\fP, except that the first character,
the <\fIentry\ type\fP>, 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.
.sp
.LP
The following represent the last-modification time of a file when
it was most recently added to or replaced in the archive:
.TP 7
<\fIabbreviated\ month\fP>
.sp
Equivalent to the format of the \fB%b\fP conversion specification
format in \fIdate\fP.
.TP 7
<\fIday-of-month\fP>
.sp
Equivalent to the format of the \fB%e\fP conversion specification
format in \fIdate\fP.
.TP 7
<\fIhour\fP>
Equivalent to the format of the \fB%H\fP conversion specification
format in \fIdate\fP.
.TP 7
<\fIminute\fP>
Equivalent to the format of the \fB%M\fP conversion specification
format in \fIdate\fP.
.TP 7
<\fIyear\fP>
Equivalent to the format of the \fB%Y\fP conversion specification
format in \fIdate\fP.
.sp
.LP
When \fILC_TIME\fP 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.
.LP
If the \fB-x\fP option is used with the \fB-v\fP option, the standard
output format shall be:
.sp
.RS
.nf

\fB"x - %s\\n", <\fP\fIfile\fP\fB>
\fP
.fi
.RE
.LP
where \fIfile\fP is the operand specified on the command line, if
\fIfile\fP operands were specified, or the name of the file
in the archive if they were not.
.SH STDERR
.LP
The standard error shall be used only for diagnostic messages. The
diagnostic message about creating a new archive when
\fB-c\fP is not specified shall not modify the exit status.
.SH OUTPUT FILES
.LP
Archives are files with unspecified formats.
.SH EXTENDED DESCRIPTION
.LP
None.
.SH EXIT STATUS
.LP
The following exit values shall be returned:
.TP 7
\ 0
Successful completion.
.TP 7
>0
An error occurred.
.sp
.SH CONSEQUENCES OF ERRORS
.LP
Default.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
None.
.SH EXAMPLES
.LP
None.
.SH RATIONALE
.LP
The archive format is not described. It is recognized that there are
several known \fIar\fP formats, which are not compatible.
The \fIar\fP 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 \fIar\fP.
.LP
Utilities such as \fIpax\fP (and its forebears \fItar\fP and \fIcpio\fP)
also provide
portable "archives". This is a not a duplication; the \fIar\fP utility
is included to provide an interface primarily for \fImake\fP and the
compilers, based on a historical model.
.LP
In historical implementations, the \fB-q\fP option (available on XSI-conforming
systems) is known to execute quickly because
\fIar\fP 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.
.LP
BSD implementations historically required applications to provide
the \fB-s\fP 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.
.LP
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.
.LP
According to the System V documentation, the options \fB-dmpqrtx\fP
are not required to begin with a hyphen ( \fB'-'\fP ).
This volume of IEEE\ Std\ 1003.1-2001 requires that a conforming application
use the leading hyphen.
.LP
The archive format used by the 4.4 BSD implementation is documented
in this RATIONALE as an example:
A file created by \fIar\fP begins with the "magic" string \fB"!<arch>\\n"\fP
\&. 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. 
.LP
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.
.LP
The modification time is the file \fIst_mtime\fP field. The user and
group IDs are the file \fIst_uid\fP and \fIst_gid\fP
fields. The file mode is the file \fIst_mode\fP field. The file size
is the file \fIst_size\fP field. The two-byte trailer is the
string \fB"`<newline>"\fP .
.LP
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 \fB"#1/"\fP 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.
.LP
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.
.LP
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.
.LP
The \fIar\fP utility description requires that (when all its members
are valid object files) \fIar\fP 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, \fIar\fP must provide it; however, \fIar\fP
does not require a symbol table.
.LP
The BSD \fB-o\fP option was omitted. It is a rare conforming application
that uses \fIar\fP to extract object code from a
library with concern for its modification time, since this can only
be of importance to \fImake\fP. Hence, since this functionality is
not deemed important for applications portability, the
modification time of the extracted files is set to the current time.
.LP
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.
.LP
Consideration was given to changing the output format of \fIar\fP
\fB-tv\fP to the same format as the output of \fIls\fP \fB-l\fP. This
would have made parsing the output of \fIar\fP the same as that of
\fIls\fP. This was rejected in part because the current \fIar\fP format
is commonly used and changes
would break historical usage. Second, \fIar\fP 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 \fIar\fP cannot know whether the archive was generated
on the same machine, it cannot tell what to report.
.LP
The text on the \fB-ur\fP option combination is historical practice-since
one filename can easily represent two different files
(for example, \fB/a/foo\fP and \fB/b/foo\fP), 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
.LP
None.
.SH SEE ALSO
.LP
\fIc99\fP , \fIdate\fP , \fIfort77\fP , \fIpax\fP , \fIstrip\fP the
Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 13, Headers,
\fI<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, 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 .