319 lines
9.2 KiB
Groff
319 lines
9.2 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
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd June 29, 1993
|
|
.Dt AR 1
|
|
.Sh NAME
|
|
.Nm ar
|
|
.Nd create and maintain library archives
|
|
.Sh SYNOPSIS
|
|
.Nm ar
|
|
.Fl d
|
|
.Op Fl \Tv
|
|
.Ar archive file ...
|
|
.Nm ar
|
|
.Fl m
|
|
.Op Fl \Tv
|
|
.Ar archive file ...
|
|
.Nm ar
|
|
.Fl m
|
|
.Op Fl abiTv
|
|
.Ar position archive file ...
|
|
.Nm ar
|
|
.Fl p
|
|
.Op Fl \Tv
|
|
.Ar archive [file ...]
|
|
.Nm ar
|
|
.Fl q
|
|
.Op Fl cTv
|
|
.Ar archive file ...
|
|
.Nm ar
|
|
.Fl r
|
|
.Op Fl cuTv
|
|
.Ar archive file ...
|
|
.Nm ar
|
|
.Fl r
|
|
.Op Fl abciuTv
|
|
.Ar position archive file ...
|
|
.Nm ar
|
|
.Fl t
|
|
.Op Fl \Tv
|
|
.Ar archive [file ...]
|
|
.Nm ar
|
|
.Fl x
|
|
.Op Fl ouTv
|
|
.Ar archive [file ...]
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm 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
|
|
.Em first
|
|
file with a matching name will be selected.
|
|
.Pp
|
|
The normal use of
|
|
.Nm ar
|
|
is for the creation and maintenance of libraries suitable for use with
|
|
the loader (see
|
|
.Xr ld 1 )
|
|
although it is not restricted to this purpose.
|
|
The options are as follows:
|
|
.Bl -tag -width indent
|
|
.It Fl a
|
|
A positioning modifier used with the options
|
|
.Fl r
|
|
and
|
|
.Fl m .
|
|
The files are entered or moved
|
|
.Em after
|
|
the archive member
|
|
.Ar position ,
|
|
which must be specified.
|
|
.It Fl b
|
|
A positioning modifier used with the options
|
|
.Fl r
|
|
and
|
|
.Fl m .
|
|
The files are entered or moved
|
|
.Em before
|
|
the archive member
|
|
.Ar position ,
|
|
which must be specified.
|
|
.It Fl c
|
|
Whenever an archive is created, an informational message to that effect
|
|
is written to standard error.
|
|
If the
|
|
.Fl c
|
|
option is specified,
|
|
.Nm ar
|
|
creates the archive silently.
|
|
.It Fl d
|
|
Delete the specified archive files.
|
|
.It Fl i
|
|
Identical to the
|
|
.Fl b
|
|
option.
|
|
.It Fl m
|
|
Move the specified archive files within the archive.
|
|
If one of the options
|
|
.Fl a ,
|
|
.Fl b
|
|
or
|
|
.Fl i
|
|
is specified, the files are moved
|
|
before or after the
|
|
.Ar position
|
|
file in the archive.
|
|
If none of those options are specified, the files are moved
|
|
to the end of the archive.
|
|
.It Fl 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.
|
|
.It Fl 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.
|
|
.It Fl 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
|
|
.Fl 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.
|
|
.It Fl 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
|
|
.Fl a ,
|
|
.Fl b
|
|
or
|
|
.Fl i
|
|
is specified.
|
|
.It Fl 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
|
|
.Xr ar 5
|
|
for more information.)
|
|
.It Fl 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.
|
|
.It Fl u
|
|
Update files.
|
|
When used with the
|
|
.Fl 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
|
|
.Fl x
|
|
option, files in the archive will be extracted
|
|
only if the archive file has a newer modification time than the file
|
|
on disk.
|
|
.It Fl v
|
|
Provide verbose output.
|
|
When used with the
|
|
.Fl d ,
|
|
.Fl m ,
|
|
.Fl q
|
|
or
|
|
.Fl x
|
|
options,
|
|
.Nm 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
|
|
.Fl r
|
|
option,
|
|
.Nm 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.
|
|
.Pp
|
|
When used with the
|
|
.Fl 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.
|
|
.Pp
|
|
When used with the
|
|
.Fl t
|
|
option,
|
|
.Nm 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
|
|
.Xr 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
|
|
.Xr date 1
|
|
format ``%b %e %H:%M %Y''), and the name of the file.
|
|
.It Fl 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.
|
|
.Pp
|
|
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
|
|
.Fl 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.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Nm ar
|
|
utility exits 0 on success, and >0 if an error occurs.
|
|
.Sh ENVIRONMENT
|
|
.Bl -tag -width indent -compact
|
|
.It Ev TMPDIR
|
|
The pathname of the directory to use when creating temporary files.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width indent -compact
|
|
.It Pa /tmp
|
|
default temporary file directory
|
|
.It Pa ar.XXXXXX
|
|
temporary file names
|
|
.El
|
|
.Sh COMPATIBILITY
|
|
By default,
|
|
.Nm 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
|
|
.Nm ar
|
|
is backward compatible with previous versions of
|
|
.Nm ar
|
|
in that it can read and write (using the
|
|
.Fl T
|
|
option) historic archives.
|
|
The
|
|
.Fl T
|
|
option is provided for compatibility only, and will be deleted
|
|
in a future release.
|
|
See
|
|
.Xr ar 5
|
|
for more information.
|
|
.Sh STANDARDS
|
|
The
|
|
.Nm ar
|
|
utility is expected to offer a superset of the
|
|
.St -p1003.2
|
|
functionality.
|
|
.Sh SEE ALSO
|
|
.Xr ld 1 ,
|
|
.Xr ranlib 1 ,
|
|
.Xr strmode 3 ,
|
|
.Xr ar 5
|