Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
AR(1)			FreeBSD	General	Commands Manual			 AR(1)

NAME
     ar, ranlib	-- manage archives

SYNOPSIS
     ar	-d [-T]	[-j] [-v] [-z] archive files ...
     ar	-m [-T]	[-a position-after] [-b	position-before] [-i position-before]
	[-j] [-s] [-z] archive files ...
     ar	-p [-T]	[-v] archive [files ...]
     ar	-r [-T]	[-a position-after] [-b	position-before] [-c]
	[-i position-before] [-j] [-s] [-u] [-v] [-z] archive files ...
     ar	-s [-j]	[-z] archive
     ar	-t [-T]	[-v] archive [files ...]
     ar	-x [-C]	[-T] [-o] [-u] [-v] archive [files ...]
     ranlib archive ...

DESCRIPTION
     The ar utility creates and	maintains groups of files combined into	an ar-
     chive.  Once an archive has been created, new files can be	added to it,
     and existing files	can be extracted, deleted or replaced.

     Files are named in	the archive by their last file name component, so if a
     file referenced by	a path containing a ``/'' 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.

     The normal	use of ar is for the creation and maintenance of libraries
     suitable for use with the link editor ld(1), although it is not
     restricted	to this	purpose.  The ar utility can create and	manage an ar-
     chive symbol table	(see 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 speci-
     fied by the -q option).

     The ranlib	utility	is used	to add an archive symbol table to an existing
     archive.

OPTIONS
     The ar utility supports the following options:

     -a	member-after
	     When used with option -m this option specifies that the archive
	     members specified by arguments files ... are moved	to after the
	     archive member named by argument member-after.  When used with
	     option -r this option specifies that the files specified by argu-
	     ments files ... are added after the archive member	named by argu-
	     ment member-after.

     -b	member-before
	     When used with option -m this option specifies that the archive
	     members specified by arguments files ... are moved	to before the
	     archive member named by argument member-before.  When used	with
	     option -r this option specifies that the files specified by argu-
	     ments files ... are added before the archive member named by
	     argument member-before.

     -c	     Suppress the informational	message	printed	when a new archive is
	     created using the -r and -q options.

     -C	     Prevent extracted files from replacing like-named files in	the
	     file system.

     -d	     Delete the	members	named by arguments files ... from the archive
	     specified by argument archive.  The archive's symbol table, if
	     present, is updated to reflect the	new contents of	the archive.

     -f	     Synonymous	with option -T.

     -i	member-before
	     Synonymous	with option -b.

     -j	     Compress the resulting archive with bzip2(1).

     -m	     Move archive members specified by arguments files ... within the
	     archive.  If a position has been specified	by one of the -a, -b
	     or	-i options, the	members	are moved to before or after the spec-
	     ified 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.

     -o	     Preserve the original modification	times of members when extract-
	     ing them.

     -p	     Write the contents	of the specified archive members named by
	     arguments files ... to standard output.  If no members were spec-
	     ified, the	contents of all	the files in the archive are written
	     in	the order they appear in the archive.

     -q	     Append the	files specified	by arguments files ... to the archive
	     specified by argument archive without checking if the files
	     already exist in the archive and without updating the archive's
	     symbol table.  If the archive file	archive	does not already
	     exist, a new archive is created.  However,	to be compatible with
	     GNU ar, option -q will update the archive's symbol	table.

     -r	     Replace (add) the files specified by arguments files ... in the
	     archive specified by argument 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
	     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 -a, -b or -i
	     is	specified.  The	archive	symbol table, if it exists, is updated
	     to	reflect	the new	state of the archive.

     -s	     Add an archive symbol table (see ar(5)) to	the archive specified
	     by	argument archive.  Invoking ar with the	-s option alone	is
	     equivalent	to invoking ranlib.

     -t	     List the files specified by arguments 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.

     -T	     Use only the first	fifteen	characters of the archive member name
	     or	command	line file name argument	when naming archive members.

     -u	     Conditionally update the archive or extract members.  When	used
	     with the -r option, files named by	arguments files	... will be
	     replaced in the archive if	they are newer than their archived
	     versions.	When used with the -x option, the members specified by
	     arguments files ... will be extracted only	if they	are newer than
	     the corresponding files in	the file system.

     -v	     Provide verbose output.  When used	with the -d, -m, -q or -x
	     options, ar gives a file-by-file description of the archive modi-
	     fication being performed, which consists of three white-space
	     seperated fields: the option letter, a dash ``-'',	and the	file
	     name.  When used with the -r option, ar displays the description
	     as	above, but the initial letter is an ``a'' if the file is added
	     to	the archive, or	an ``r'' if the	file replaces a	file already
	     in	the archive.  When used	with the -p option, the	name of	the
	     file enclosed in ``<'' and	``>'' characters is written to stan-
	     dard 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	-t option, ar displays eight
	     whitespace	separated fields: the file permissions as displayed by
	     strmode(3), decimal user and group	IDs separated by a slash (
	     ``/''), the file size in bytes, the file modification time	in
	     strftime(3) format	``%b %e	%H:%M %Y'', and	the name of the	file.

     -x	     Extract archive members specified by arguments 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 -o option was specified.

     -z	     Compress the resulting archive with gzip(1).

EXAMPLES
     To	create a new archive ex.a containing three files ex1.o,	ex2.o and
     ex3.o, use:
	   ar -rc ex.a ex1.o ex2.o ex3.o

     To	add an archive symbol table to an existing archive ex.a, use:
	   ar -s ex.a

     To	delete file ex1.o from archive ex.a, use:
	   ar -d ex.a ex1.o

     To	verbosely list the contents of archive ex.a, use:
	   ar -tv ex.a

DIAGNOSTICS
     The ar utility exits 0 on success,	and >0 if an error occurs.

SEE ALSO
     ld(1), archive(3),	elf(3),	strftime(3), strmode(3), ar(5)

HISTORY
     An	ar command first appeared in AT&T UNIX Version 1.  In FreeBSD 8.0, Kai
     Wang <kaiw@FreeBSD.org> reimplemented ar and ranlib using the Streaming
     Archive Library (libarchive, -larchive) and the ELF Parsing Library
     (libelf, -lelf).

FreeBSD	9.3			August 31, 2007			   FreeBSD 9.3

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | DIAGNOSTICS | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=ar&sektion=1&manpath=FreeBSD+8.0-RELEASE>

home | help