summaryrefslogtreecommitdiffstats
path: root/usr.bin/ar/ar.1
diff options
context:
space:
mode:
Diffstat (limited to 'usr.bin/ar/ar.1')
-rw-r--r--usr.bin/ar/ar.1257
1 files changed, 257 insertions, 0 deletions
diff --git a/usr.bin/ar/ar.1 b/usr.bin/ar/ar.1
new file mode 100644
index 0000000..026aed6
--- /dev/null
+++ b/usr.bin/ar/ar.1
@@ -0,0 +1,257 @@
+.\" 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
+.\"
+.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)
OpenPOWER on IntegriCloud