265 lines
9.0 KiB
Groff
265 lines
9.0 KiB
Groff
.\" Copyright (c) 1990, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to Berkeley by
|
|
.\" Hugh Smith at The University of Guelph.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)ar.1 8.1 (Berkeley) 6/29/93
|
|
.\" $Id$
|
|
.\"
|
|
.TH AR 1 "June 29, 1993"
|
|
.AT 3
|
|
.SH NAME
|
|
ar \- create and maintain library archives
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
ar -d [-Tv] archive file ...
|
|
ar -m [-Tv] archive file ...
|
|
ar -m [-abiTv] position archive file ...
|
|
ar -p [-Tv] archive [file ...]
|
|
ar -q [-cTv] archive file ...
|
|
ar -r [-cuTv] archive file ...
|
|
ar -r [-abciuTv] position archive file ...
|
|
ar -t [-Tv] archive [file ...]
|
|
ar -x [-ouTv] archive [file ...]
|
|
.fi
|
|
.ft R
|
|
.SH DESCRIPTION
|
|
The
|
|
.I ar
|
|
utility creates and maintains groups of files combined into an archive.
|
|
Once an archive has been created, new files can be added and existing
|
|
files can be extracted, deleted, or replaced.
|
|
.PP
|
|
Files are named in the archive by a single component, i.e., if a file
|
|
referenced by a path containing a slash (``/'') is archived it will be
|
|
named by the last component of that path.
|
|
When matching paths listed on the command line against file names stored
|
|
in the archive, only the last component of the path will be compared.
|
|
.PP
|
|
All informational and error messages use the path listed on the command
|
|
line, if any was specified; otherwise the name in the archive is used.
|
|
If multiple files in the archive have the same name, and paths are listed
|
|
on the command line to ``select'' archive files for an operation, only the
|
|
.B first
|
|
file with a matching name will be selected.
|
|
.PP
|
|
The normal use of
|
|
.I ar
|
|
is for the creation and maintenance of libraries suitable for use with
|
|
the loader (see
|
|
.IR ld (1)),
|
|
although it is not restricted to this purpose.
|
|
The options are as follows:
|
|
.TP
|
|
\-a
|
|
A positioning modifier used with the options \-r and \-m.
|
|
The files are entered or moved
|
|
.B after
|
|
the archive member
|
|
.IR position ,
|
|
which must be specified.
|
|
.TP
|
|
\-b
|
|
A positioning modifier used with the options \-r and \-m.
|
|
The files are entered or moved
|
|
.B before
|
|
the archive member
|
|
.IR position ,
|
|
which must be specified.
|
|
.TP
|
|
\-c
|
|
Whenever an archive is created, an informational message to that effect
|
|
is written to standard error.
|
|
If the \-c option is specified,
|
|
.I ar
|
|
creates the archive silently.
|
|
.TP
|
|
\-d
|
|
Delete the specified archive files.
|
|
.TP
|
|
\-i
|
|
Identical to the \-b option.
|
|
.TP
|
|
\-m
|
|
Move the specified archive files within the archive.
|
|
If one of the options \-a, \-b or \-i is specified, the files are moved
|
|
before or after the
|
|
.I position
|
|
file in the archive.
|
|
If none of those options are specified, the files are moved
|
|
to the end of the archive.
|
|
.TP
|
|
\-o
|
|
Set the access and modification times of extracted files to the
|
|
modification time of the file when it was entered into the archive.
|
|
This will fail if the user is not the owner of the extracted file
|
|
or the super-user.
|
|
.TP
|
|
\-p
|
|
Write the contents of the specified archive files to the standard output.
|
|
If no files are specified, the contents of all the files in the archive
|
|
are written in the order they appear in the archive.
|
|
.TP
|
|
\-q
|
|
(Quickly) append the specified files to the archive.
|
|
If the archive does not exist a new archive file is created.
|
|
Much faster than the \-r option, when creating a large archive
|
|
piece-by-piece, as no checking is done to see if the files already
|
|
exist in the archive.
|
|
.TP
|
|
\-r
|
|
Replace or add the specified files to the archive.
|
|
If the archive does not exist a new archive file is created.
|
|
Files that replace existing files do not change the order of the files
|
|
within the archive.
|
|
New files are appended to the archive unless one of the options \-a, \-b
|
|
or \-i is specified.
|
|
.TP
|
|
\-T
|
|
Select and/or name archive members using only the first fifteen characters
|
|
of the archive member or command line file name.
|
|
The historic archive format had sixteen bytes for the name, but some
|
|
historic archiver and loader implementations were unable to handle names
|
|
that used the entire space.
|
|
This means that file names that are not unique in their first fifteen
|
|
characters can subsequently be confused.
|
|
A warning message is printed to the standard error output if any file
|
|
names are truncated.
|
|
(See
|
|
.IR ar (5)
|
|
for more information.)
|
|
.TP
|
|
\-t
|
|
List the specified files in the order in which they appear in the archive,
|
|
each on a separate line.
|
|
If no files are specified, all files in the archive are listed.
|
|
.TP
|
|
\-u
|
|
Update files.
|
|
When used with the \-r option, files in the archive will be replaced
|
|
only if the disk file has a newer modification time than the file in
|
|
the archive.
|
|
When used with the \-x option, files in the archive will be extracted
|
|
only if the archive file has a newer modification time than the file
|
|
on disk.
|
|
.TP
|
|
\-v
|
|
Provide verbose output.
|
|
When used with the \-d, \-m, \-q or \-x options,
|
|
.I ar
|
|
gives a file-by-file description of the archive modification.
|
|
This description consists of three, white-space separated fields: the
|
|
option letter, a dash (``-'') and the file name.
|
|
When used with the \-r option,
|
|
.I ar
|
|
displays the description as above, but the initial letter is an ``a'' if
|
|
the file is added to the archive and an ``r'' if the file replaces a file
|
|
already in the archive.
|
|
.IP
|
|
When used with the \-p option,
|
|
the name of each printed file,
|
|
enclosed in less-than (``<'') and greater-than (``>'') characters,
|
|
is written to the standard output before
|
|
the contents of the file;
|
|
it is preceded by a single newline character, and
|
|
followed by two newline characters.
|
|
.IP
|
|
When used with the \-t option,
|
|
.I ar
|
|
displays an ``ls -l'' style listing of information about the members of
|
|
the archive.
|
|
This listing consists of eight, white-space separated fields:
|
|
the file permissions (see
|
|
.IR strmode (3)),
|
|
the decimal user and group ID's separated by a single slash (``/''),
|
|
the file size (in bytes), the file modification time (in the
|
|
.IR date (1)
|
|
format ``%b %e %H:%M %Y''), and the name of the file.
|
|
.TP
|
|
\-x
|
|
Extract the specified archive members into the files named by the command
|
|
line arguments.
|
|
If no members are specified, all the members of the archive are extracted into
|
|
the current directory.
|
|
.IP
|
|
If the file does not exist, it is created; if it does exist, the owner
|
|
and group will be unchanged.
|
|
The file access and modification times are the time of the extraction
|
|
(but see the \-o option).
|
|
The file permissions will be set to those of the file when it was entered
|
|
into the archive; this will fail if the user is not the owner of the
|
|
extracted file or the super-user.
|
|
.PP
|
|
The
|
|
.I ar
|
|
utility exits 0 on success, and >0 if an error occurs.
|
|
.SH ENVIRONMENT
|
|
.TP
|
|
TMPDIR
|
|
The pathname of the directory to use when creating temporary files.
|
|
.SH FILES
|
|
.TP 14
|
|
/tmp
|
|
default temporary file directory
|
|
.TP 14
|
|
ar.XXXXXX
|
|
temporary file names
|
|
.SH COMPATIBILITY
|
|
By default,
|
|
.I ar
|
|
writes archives that may be incompatible with historic archives, as
|
|
the format used for storing archive members with names longer than
|
|
fifteen characters has changed.
|
|
This implementation of
|
|
.I ar
|
|
is backward compatible with previous versions of
|
|
.I ar
|
|
in that it can read and write (using the \-T option) historic archives.
|
|
The \-T option is provided for compatibility only, and will be deleted
|
|
in a future release.
|
|
See
|
|
.IR ar (5)
|
|
for more information.
|
|
.SH STANDARDS
|
|
The
|
|
.I ar
|
|
utility is expected to offer a superset of the POSIX 1003.2 functionality.
|
|
.SH "SEE ALSO"
|
|
ld(1), ranlib(1), strmode(3), ar(5)
|
|
.SH HISTORY
|
|
A
|
|
.I ar
|
|
command appeared in
|
|
Version 1 AT&T UNIX.
|
|
|