path: root/man-pages-posix-2017/man1p/ar.1p

'\" 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 .