.TH ar "" "" Command
.PC "The librarian/archiver"
\fBar\fR \fIoption \fB[\fImodifier\^\fB][\fIposition\^\fB] \fIarchive \fB[\fImember ...\^\fB]\fR
.PP
.HS
.SH Options:
.IC \fBd\fR
Delete given members
.IC \fBm\fR
Move member to indicated position (default, end)
.IC \fBp\fR
Print members
.IC \fBq\fR
Quick append, put members at end with no checking
.IC \fBr\fR
Replace each member specified in the archive
.IC \fBt\fR
Print a table of members (default, all)
.IC \fBx\fR
Extract the specified members (default, all)
.SH Modifiers:
.IC \fBa\fR
Place new member after \fIposition\fR in archive
.IC \fBb\fR
Place new member before \fIposition\fR in archive
.IC \fBc\fR
Suppress message when new archive is created
.IC \fBi\fR
Insert new member before \fIposition\fR in archive
.IC \fBk\fR
Preserve modify time of file
(with options \fBr\fR, \fBq\fR, or \fBx\fR)
.IC \fBl\fR
Use current directory for temporaries
(default, \fB/tmp\fR)
.IC \fBs\fR
Update ranlib header even if not present
(with options \fBr\fR or \fBm\fR)
.IC \fBu\fR
Update: replace members only if newer than
those in archive
.IC \fBv\fR
Print extra information when used with certain options
.HE
The librarian
.B ar
edits and examines libraries.
It combines several files into a file called an
.I archive
or
.IR library .
Archives reduce the size of directories and allow
many files to be handled as a single unit.
The principal use of archives is for libraries of object files.
The linker
.B ld
understands the archive format, and can search
libraries of object files to resolve
undefined references in a program.
.SH "Options and Modifiers"
The mandatory
.I option
argument consists of one of the
following command keys:
.IP "\fBd\fR" 0.3i
Delete each given
.I member
from
.IR archive .
The
.B ranlib
header is updated if present.
.IP "\fBm\fR"
Move each given
.I member
within
.IR archive .
If no
.I modifier
is given, move each
.I member
to the end.
The ranlib header is modified if present.
.IP "\fBp\fR"
Print each
.IR member .
This is useful only with archives of text files.
.IP \fBq\fR
Quick append:
append each
.I member
to the end of
.I archive
unconditionally.
The ranlib header is not updated.
.IP "\fBr\fR"
Replace each
.I member
of
.IR archive .
If
.I archive
does not exist, create it.
The optional
.I modifier
specifies how to perform the replacement, as described below.
The ranlib header is modified if present.
.IP "\fBt\fR"
Print a table of contents
that lists each
.I member
specified.
If none is given, list all in
.IR archive .
The modifier
.B v
tells
.B ar
to give you additional information.
.IP "\fBx\fR"
Extract each given
.I member
and place it into the current directory.
If none is specified, extract all members.
.I archive
is not changed.
.PP
The
.I modifier
may be one of the following.
The modifiers
\fBa\fR, \fBb\fR, \fBi\fR, and \fBu\fR
may be used only with the
.B m
and
.B r
options.
.IP \fBa\fR 0.3i
If
.I member
does not exist in
.IR archive ,
insert it after the member named by the given
.IR position .
.IP \fBb\fR
If
.I member
does not exist in
.IR archive ,
insert it before the member named by the given
.IR position .
.IP \fBc\fR
Suppress the message normally printed when
.B ar
creates an
archive.
.IP \fBi\fR
If
.I member
does not exist in
.IR archive ,
insert it before the member named by the given
.IR position .
This is the same as the
.B b
modifier, described above.
.IP \fBk\fR
Preserve the modify time of a file.
This modifier is useful only with the
.BR r ,
.BR q ,
and
.B x
options.
.IP \fBs\fR
Modify an archive's ranlib header, or create it if it does not
exist.
This must be used for archives read by the linker
.BR ld .
.IP \fBu\fR
Update
.I archive
only
if
.I member
is newer than the version in the
.IR archive .
.IP \fBv\fR
Generate verbose messages.
.PP
Note that because
.B ar
was created before \*(UN established the standard of
introducing an option with a hyphen.
Therefore, the syntax of options to
.B ar
differs from most other \*(CO commands:
.B ar
expects all options and modifiers to be clumped together as its first argument,
without an introductory hyphen.
For example, to use the option
.B r
with the modifiers
.B c
and
.B s
on library
.B libname.a
and objects
.B file1.o
through
.BR file3.o ,
type the following command:
.DM
	# RIGHT!
	ar rcs libname.a file1.o file2.o file3.o
.DE
.PP
The syntax
.DM
	# WRONG!
	ar r -s libname.a file1.o file2.o file3.o
.DE
.PP
creates an archive named \fB\-s\fR, which you may have some trouble
removing.
.PP
.II ARHEAD
.II ARTAIL
.B ar
reads the environmental variables
.B ARHEAD
and
.B ARTAIL
and appends them to, respectively, the beginning and end of its command line.
For example, to ensure that
.B ar
is always executed with the \fBc\fR modifier, insert the following into your
.BR .profile :
.DM
	export ARHEAD=c
.DE
.SH "Library Structure"
All archives are written into a specialized file format.
Each archive starts with a \*(QLmagic string\*(QR called
.BR ARMAG ,
which identifies the file as an archive.
The members of the archive
follow the magic number;
each is preceded by an
.B ar_hdr
structure.
For information on this structure, see
.BR ar.h .
The structure is followed the data of the file, which occupy the number of bytes
specified by the variable
.BR ar_size .
.SH "See Also"
.Xr ar.h, ar.h
.Xr commands, commands
.Xr ld, ld
.Xr nm, nm
.Xr ranlib ranlib
.SH Notes
Each library that you create should have a name that begins with ``lib''
and ends with ``.a''.
The prefix ``lib'' lets you call that library with the
.B \-l
option to the command
.BR cc ;
and the linker
.B ld
ignores archives whose names do not end in \fB.a\fR.
