diff options
author | kaiw <kaiw@FreeBSD.org> | 2008-02-21 10:52:31 +0000 |
---|---|---|
committer | kaiw <kaiw@FreeBSD.org> | 2008-02-21 10:52:31 +0000 |
commit | bd49e931f20cf4f25d0c085cf7b048efe16cb93b (patch) | |
tree | d7041e81552890443b432a04c0b9adb7cfa9afeb /usr.bin/ar/ar.1 | |
parent | afb9fa5a4b87c13a6d671aa0b02c9e13af0f4146 (diff) | |
download | FreeBSD-src-bd49e931f20cf4f25d0c085cf7b048efe16cb93b.zip FreeBSD-src-bd49e931f20cf4f25d0c085cf7b048efe16cb93b.tar.gz |
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.
Diffstat (limited to 'usr.bin/ar/ar.1')
-rw-r--r-- | usr.bin/ar/ar.1 | 407 |
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 . |