mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-25 11:37:56 +00:00
0e479ac8f7
When set, it forces all timestamps and owners to zero and modes to 0644. Useful for producing libraries that are bitwise identical across multiple build runs. Submitted by: Erik Cederstrand Reviewed by: Kai Wang
416 lines
9.9 KiB
Groff
416 lines
9.9 KiB
Groff
.\" Copyright (c) 2007 Joseph Koshy. All rights reserved.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" This software is provided by Joseph Koshy ``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 Joseph Koshy 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd May 17, 2010
|
|
.Dt AR 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ar ,
|
|
.Nm ranlib
|
|
.Nd manage archives
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Fl d
|
|
.Op Fl T
|
|
.Op Fl j
|
|
.Op Fl v
|
|
.Op Fl z
|
|
.Ar archive
|
|
.Ar files ...
|
|
.Nm
|
|
.Fl m
|
|
.Op Fl T
|
|
.Op Fl a Ar position-after
|
|
.Op Fl b Ar position-before
|
|
.Op Fl i Ar position-before
|
|
.Op Fl j
|
|
.Op Fl s
|
|
.Op Fl z
|
|
.Ar archive
|
|
.Ar files ...
|
|
.Nm
|
|
.Fl p
|
|
.Op Fl T
|
|
.Op Fl v
|
|
.Ar archive
|
|
.Op Ar files ...
|
|
.Nm
|
|
.Fl r
|
|
.Op Fl T
|
|
.Op Fl a Ar position-after
|
|
.Op Fl b Ar position-before
|
|
.Op Fl c
|
|
.Op Fl D
|
|
.Op Fl i Ar position-before
|
|
.Op Fl j
|
|
.Op Fl s
|
|
.Op Fl u
|
|
.Op Fl v
|
|
.Op Fl z
|
|
.Ar archive
|
|
.Ar files ...
|
|
.Nm
|
|
.Fl s
|
|
.Op Fl j
|
|
.Op Fl z
|
|
.Ar archive
|
|
.Nm
|
|
.Fl t
|
|
.Op Fl T
|
|
.Op Fl v
|
|
.Ar archive
|
|
.Op Ar files ...
|
|
.Nm
|
|
.Fl x
|
|
.Op Fl C
|
|
.Op Fl T
|
|
.Op Fl o
|
|
.Op Fl u
|
|
.Op Fl v
|
|
.Ar archive
|
|
.Op Ar files ...
|
|
.Nm ranlib
|
|
.Ar archive ...
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility creates and maintains groups of files combined into an
|
|
archive.
|
|
Once an archive has been created, new files can be added to it, and
|
|
existing files can be extracted, deleted or replaced.
|
|
.Pp
|
|
Files are named in the archive by their last file name component,
|
|
so if a file referenced by a path containing a
|
|
.Dq /
|
|
is archived, it will be named by the last component of the path.
|
|
Similarly 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
|
|
The normal use of
|
|
.Nm
|
|
is for the creation and maintenance of libraries suitable for use
|
|
with the link editor
|
|
.Xr ld 1 ,
|
|
although it is not restricted to this purpose.
|
|
The
|
|
.Nm
|
|
utility can create and manage an archive symbol table (see
|
|
.Xr ar 5 )
|
|
used to speed up link editing operations.
|
|
If a symbol table is present in an archive, it will be
|
|
kept up-to-date by subsequent operations on the archive (excepting
|
|
the quick update specified by the
|
|
.Fl q
|
|
option).
|
|
.Pp
|
|
The
|
|
.Nm ranlib
|
|
utility is used to add an archive symbol table
|
|
to an existing archive.
|
|
.Sh OPTIONS
|
|
The
|
|
.Nm
|
|
utility supports the following options:
|
|
.Bl -tag -width indent
|
|
.It Fl a Ar member-after
|
|
When used with option
|
|
.Fl m
|
|
this option specifies that the archive members specified by
|
|
arguments
|
|
.Ar files ...
|
|
are moved to after the archive member named by argument
|
|
.Ar member-after .
|
|
When used with option
|
|
.Fl r
|
|
this option specifies that the files specified by arguments
|
|
.Ar files ...
|
|
are added after the archive member named by argument
|
|
.Ar member-after .
|
|
.It Fl b Ar member-before
|
|
When used with option
|
|
.Fl m
|
|
this option specifies that the archive members specified by
|
|
arguments
|
|
.Ar files ...
|
|
are moved to before the archive member named by argument
|
|
.Ar member-before .
|
|
When used with option
|
|
.Fl r
|
|
this option specifies that the files specified by arguments
|
|
.Ar files ...
|
|
are added before the archive member named by argument
|
|
.Ar member-before .
|
|
.It Fl c
|
|
Suppress the informational message printed when a new archive is
|
|
created using the
|
|
.Fl r
|
|
and
|
|
.Fl q
|
|
options.
|
|
.It Fl C
|
|
Prevent extracted files from replacing like-named files
|
|
in the file system.
|
|
.It Fl d
|
|
Delete the members named by arguments
|
|
.Ar files ...
|
|
from the archive specified by argument
|
|
.Ar archive .
|
|
The archive's symbol table, if present, is updated to reflect
|
|
the new contents of the archive.
|
|
.It Fl D
|
|
When used in combination with the
|
|
.Fl r
|
|
or
|
|
.Fl q
|
|
option, insert 0's instead of the real mtime, uid and gid values
|
|
and 0644 instead of file mode from the members named by arguments
|
|
.Ar files ... .
|
|
This ensures that checksums on the resulting archives are reproducible
|
|
when member contents are identical.
|
|
.It Fl f
|
|
Synonymous with option
|
|
.Fl T .
|
|
.It Fl i Ar member-before
|
|
Synonymous with option
|
|
.Fl b .
|
|
.It Fl j
|
|
This option is accepted but ignored.
|
|
.It Fl m
|
|
Move archive members specified by arguments
|
|
.Ar files ...
|
|
within the archive.
|
|
If a position has been specified by one of the
|
|
.Fl a ,
|
|
.Fl b
|
|
or
|
|
.Fl i
|
|
options, the members are moved to before or after the specified
|
|
position.
|
|
If no position has been specified, the specified members are moved
|
|
to the end of the archive.
|
|
If the archive has a symbol table, it is updated to reflect the
|
|
new contents of the archive.
|
|
.It Fl o
|
|
Preserve the original modification times of members when extracting
|
|
them.
|
|
.It Fl p
|
|
Write the contents of the specified archive members named by
|
|
arguments
|
|
.Ar files ...
|
|
to standard output.
|
|
If no members were specified, the contents of all the files in the
|
|
archive are written in the order they appear in the archive.
|
|
.It Fl q
|
|
Append the files specified by arguments
|
|
.Ar files ...
|
|
to the archive specified by argument
|
|
.Ar archive
|
|
without checking if the files already exist in the archive and
|
|
without updating the archive's symbol table.
|
|
If the archive file
|
|
.Ar archive
|
|
does not already exist, a new archive is created.
|
|
However, to be compatible with GNU
|
|
.Nm ,
|
|
option
|
|
.Fl q
|
|
will update the archive's symbol table.
|
|
.It Fl r
|
|
Replace (add) the files specified by arguments
|
|
.Ar files ...
|
|
in the archive specified by argument
|
|
.Ar archive ,
|
|
creating the archive if necessary.
|
|
Files that replace existing files do not change the order of files
|
|
within the archive.
|
|
If a file named in arguments
|
|
.Ar files ...
|
|
does not exist, existing members in the archive that match that
|
|
name are not changed.
|
|
New files are added to the end of the archive unless one of the
|
|
positioning options
|
|
.Fl a ,
|
|
.Fl b
|
|
or
|
|
.Fl i
|
|
is specified.
|
|
The archive symbol table, if it exists, is updated to reflect the
|
|
new state of the archive.
|
|
.It Fl s
|
|
Add an archive symbol table (see
|
|
.Xr ar 5 )
|
|
to the archive specified by argument
|
|
.Ar archive .
|
|
Invoking
|
|
.Nm
|
|
with the
|
|
.Fl s
|
|
option alone is equivalent to invoking
|
|
.Nm ranlib .
|
|
.It Fl t
|
|
List the files specified by arguments
|
|
.Ar files ...
|
|
in the order in which they appear in the archive, one per line.
|
|
If no files are specified, all files in the archive are listed.
|
|
.It Fl T
|
|
Use only the first fifteen characters of the archive member name or
|
|
command line file name argument when naming archive members.
|
|
.It Fl u
|
|
Conditionally update the archive or extract members.
|
|
When used with the
|
|
.Fl r
|
|
option, files named by arguments
|
|
.Ar files ...
|
|
will be replaced in the archive if they are newer than their
|
|
archived versions.
|
|
When used with the
|
|
.Fl x
|
|
option, the members specified by arguments
|
|
.Ar files ...
|
|
will be extracted only if they are newer than the corresponding
|
|
files in the file system.
|
|
.It Fl v
|
|
Provide verbose output.
|
|
When used with the
|
|
.Fl d ,
|
|
.Fl m ,
|
|
.Fl q
|
|
or
|
|
.Fl x
|
|
options,
|
|
.Nm
|
|
gives a file-by-file description of the archive modification being
|
|
performed, which consists of three white-space separated fields:
|
|
the option letter, a dash
|
|
.Dq "-" ,
|
|
and the file name.
|
|
When used with the
|
|
.Fl r
|
|
option,
|
|
.Nm
|
|
displays the description as above, but the initial letter is an
|
|
.Dq a
|
|
if the file is added to the archive, or an
|
|
.Dq r
|
|
if the file replaces a file already in the archive.
|
|
When used with the
|
|
.Fl p
|
|
option, the name of the file enclosed in
|
|
.Dq <
|
|
and
|
|
.Dq >
|
|
characters is written to standard output preceded by a single newline
|
|
character and followed by two newline characters.
|
|
The contents of the named file follow the file name.
|
|
When used with the
|
|
.Fl t
|
|
option,
|
|
.Nm
|
|
displays eight whitespace separated fields:
|
|
the file permissions as displayed by
|
|
.Xr strmode 3 ,
|
|
decimal user and group IDs separated by a slash (
|
|
.Dq / Ns ) ,
|
|
the file size in bytes, the file modification time in
|
|
.Xr strftime 3
|
|
format
|
|
.Dq "%b %e %H:%M %Y" ,
|
|
and the name of the file.
|
|
.It Fl x
|
|
Extract archive members specified by arguments
|
|
.Ar files ...
|
|
into the current directory.
|
|
If no members have been specified, extract all members of the archive.
|
|
If the file corresponding to an extracted member does not exist it
|
|
will be created.
|
|
If the file corresponding to an extracted member does exist, its owner
|
|
and group will not be changed while its contents will be overwritten
|
|
and its permissions will set to that entered in the archive.
|
|
The file's access and modification time would be that of the time
|
|
of extraction unless the
|
|
.Fl o
|
|
option was specified.
|
|
.It Fl z
|
|
This option is accepted but ignored.
|
|
.El
|
|
.Sh EXAMPLES
|
|
To create a new archive
|
|
.Pa ex.a
|
|
containing three files
|
|
.Pa ex1.o ,
|
|
.Pa ex2.o
|
|
and
|
|
.Pa ex3.o ,
|
|
use:
|
|
.Dl "ar -rc ex.a ex1.o ex2.o ex3.o"
|
|
.Pp
|
|
To add an archive symbol table to an existing archive
|
|
.Pa ex.a ,
|
|
use:
|
|
.Dl "ar -s ex.a"
|
|
.Pp
|
|
To delete file
|
|
.Pa ex1.o
|
|
from archive
|
|
.Pa ex.a ,
|
|
use:
|
|
.D1 "ar -d ex.a ex1.o"
|
|
.Pp
|
|
To verbosely list the contents of archive
|
|
.Pa ex.a ,
|
|
use:
|
|
.D1 "ar -tv ex.a"
|
|
.Sh DIAGNOSTICS
|
|
.Ex -std
|
|
.Sh SEE ALSO
|
|
.Xr ld 1 ,
|
|
.Xr archive 3 ,
|
|
.Xr elf 3 ,
|
|
.Xr strftime 3 ,
|
|
.Xr strmode 3 ,
|
|
.Xr ar 5
|
|
.\" .Sh COMPATIBILITY
|
|
.\" .Nm
|
|
.\" is expected to be compatible with GNU and SVR4
|
|
.\" .Nm .
|
|
.\" .Sh STANDARDS
|
|
.\" Do the POSIX/SuSv3 standards have anything to say about AR(1)?
|
|
.Sh HISTORY
|
|
An
|
|
.Nm
|
|
command first appeared in AT&T UNIX Version 1.
|
|
In
|
|
.Fx 8.0 ,
|
|
.An "Kai Wang" Aq kaiw@FreeBSD.org
|
|
reimplemented
|
|
.Nm
|
|
and
|
|
.Nm ranlib
|
|
using the
|
|
.Lb libarchive
|
|
and the
|
|
.Lb libelf .
|