Import ar(1) front-end. (aka 'BSD' ar)

Reviewed by: 		jkoshy
Approved by:		jkoshy (mentor)
Tested by:		erwin (ports build test on pointyhat)
Sponsored by:		Google Summer of Code 2007
Reviewed by (earlier version): Jaakko Heinonen <jh[AT]saunalahti.fi>
Tested by (earlier version): Steve Kargl <sgk[AT]troutmask.apl.washington.edu>
Tested by (earlier version): Martin Voros <martin_voros[AT]yahoo.com>
Tested by (earlier version): swell.k[AT]gmail.com
Tested by (earlier version): joel
Tested by (earlier version): Alexey Shuvaev <shuvaev[AT]physik.uni-wuerzburg.de>
Tested by (earlier version): Arjan van Leeuwen <avleeuwen[AT]gmail.com>

Thanks to gabor@ for building ports for it.
Thanks to erwin@ and kris@ for scheduling the ports build test on pointyhat.
And thanks to many others for their feedback.

1 files changed, 407 insertions, 0 deletions

diff --git a/usr.bin/ar/ar.1 b/usr.bin/ar/ar.1
new file mode 100644
index 0000000..0982bda
--- /dev/null
+++ b/usr.bin/ar/ar.1
@@ -0,0 +1,407 @@
+.\" 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 August 31, 2007
+.Os
+.Dr AR 1
+.Dt RANLIB 1
+.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 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 upto-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 f
+Synonymous with option
+.Fl T .
+.It Fl i Ar member-before
+Synonymous with option
+.Fl b .
+.It Fl j
+Compress the resulting archive with
+.Xr bzip2 1 .
+.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 ,
+.Fl q
+is implemented as a synonym for
+.Fl r .
+.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 seperated 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
+.Dr 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
+Compress the resulting archive with
+.Xr gzip 1 .
+.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 ,
+.An "Kai Wang" Aq kaiw@FreeBSD.org
+reimplemented
+.Nm ar
+and
+.Nm ranlib
+using the
+.Lb libarchive
+and the
+.Lb libelf .