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

FreeBSD Manual Pages

  
 
  

home | help
AR(1)			  BSD General Commands Manual			 AR(1)

NAME
     ar, ranlib	-- manage archives

SYNOPSIS
     ar	-d [-T]	[-f] [-j] [-v] [-z] archive file ...
     ar	-m [-T]	[-a position-after] [-b	position-before] [-f]
	[-i position-before] [-j] [-s |	-S] [-z] archive file ...
     ar	-p [-T]	[-f] [-v] archive [file	...]
     ar	-q [-T]	[-c] [-D] [-f] [-s | -S] [-U] [-v] [-z]	archive	file ...
     ar	-r [-T]	[-a position-after] [-b	position-before] [-c] [-D] [-f]
	[-i position-before] [-j] [-s |	-S] [-u] [-U] [-v] [-z]	archive
	file ...
     ar	-s [-j]	[-z] archive
     ar	-t [-f]	[-T] [-v] archive [file	...]
     ar	-x [-C]	[-T] [-f] [-o] [-u] [-v] archive [file ...]
     ar	-M
     ranlib [-D] [-U] 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 re-
     stricted 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.

     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 file ... 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 file	... 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 file ... 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 file	... are	added before the archive member	named by argu-
	     ment 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 file	... from the archive
	     specified by argument archive.  The archive's symbol table, if
	     present, is updated to reflect the	new contents of	the archive.

     -D	     When used in combination with the -r or -q	option,	with the -s
	     option without other options, or when invoked as ranlib, insert
	     0's instead of the	real mtime, uid	and gid	values and 0644	in-
	     stead of file mode	from the members named by arguments file ....
	     This ensures that checksums on the	resulting archives are repro-
	     ducible when member contents are identical.  This option is en-
	     abled by default.	If multiple -D and -U options are specified on
	     the command line, the final one takes precedence.

     -f	     Synonymous	with option -T.

     -i	member-before
	     Synonymous	with option -b.

     -j	     This option is accepted but ignored.

     -l	     This option is accepted for compatibility with GNU	ar(1), but is
	     ignored.

     -m	     Move archive members specified by arguments file ... 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.

     -M	     Read and execute MRI librarian commands from standard input.  The
	     commands understood by the	ar utility are described in the	sec-
	     tion MRI Librarian	Commands.

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

     -p	     Write the contents	of the specified archive members named by ar-
	     guments file ... to standard output.  If no members were speci-
	     fied, 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 file ... to the archive
	     specified by argument archive without checking if the files al-
	     ready exist in the	archive.  The archive symbol table will	be up-
	     dated as needed.  If the file specified by	the argument archive
	     does not already exist, a new archive will	be created.

     -r	     Replace (add) the files specified by arguments file ... in	the
	     archive specified by argument archive, creating the archive if
	     necessary.	 Replacing existing members will not change the	order
	     of	members	within the archive.  If	a file named in	arguments
	     file ... 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.

     -S	     Do	not generate an	archive	symbol table.

     -t	     List the files specified by arguments file	... 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 file ... will	be re-
	     placed in the archive if they are newer than their	archived ver-
	     sions.  When used with the	-x option, the members specified by
	     arguments file ...	will be	extracted only if they are newer than
	     the corresponding files in	the file system.

     -U	     When used in combination with the -r or -q	option,	insert the
	     real mtime, uid and gid, and file mode values from	the members
	     named by arguments	file ....  If multiple -D and -U options are
	     specified on the command line, the	final one takes	precedence.

     -v	     Provide verbose output.  When used	with the -d, -m, -q or -x op-
	     tions, ar gives a file-by-file description	of the archive modifi-
	     cation being performed, which consists of three white-space sepa-
	     rated 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 en-
	     closed in "<" and ">" characters is written to standard output
	     preceded by a single newline character and	followed by two	new-
	     line 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.

     -V	     Print a version string and	exit.

     -x	     Extract archive members specified by arguments file ... into the
	     current directory.	 If no members have been specified, extract
	     all members of the	archive.  If the file corresponding to an ex-
	     tracted 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	     This option is accepted but ignored.

   MRI Librarian Commands
     If	the -M option is specified, the	ar utility will	read and execute com-
     mands from	its standard input.  If	standard input is a terminal, the ar
     utility will display the prompt "AR >" before reading a line, and will
     continue operation	even if	errors are encountered.	 If standard input is
     not a terminal, the ar utility will not display a prompt and will termi-
     nate execution on encountering an error.

     Each input	line contains a	single command.	 Words in an input line	are
     separated by whitespace characters.  The first word of the	line is	the
     command, the remaining words are the arguments to the command.  The com-
     mand word may be specified	in either case.	 Arguments may be separated by
     commas or blanks.

     Empty lines are allowed and are ignored.  Long lines are continued	by
     ending them with the "+" character.

     The "*" and ";" characters	start a	comment.  Comments extend till the end
     of	the line.

     When executing an MRI librarian script the	ar utility works on a tempo-
     rary copy of an archive.  Changes to the copy are made permanent using
     the save command.

     Commands understood by the	ar utility are:

     addlib archive | addlib archive (member [,	member]...)
	     Add the contents of the archive named by argument archive to the
	     current archive.  If specific members are named using the argu-
	     ments member, then	those members are added	to the current ar-
	     chive.  If	no members are specified, the entire contents of the
	     archive are added to the current archive.

     addmod member [, member]...
	     Add the files named by arguments member to	the current archive.

     clear   Discard all the contents of the current archive.

     create archive
	     Create a new archive named	by the argument	archive, and makes it
	     the current archive.  If the named	archive	already	exists,	it
	     will be overwritten when the save command is issued.

     delete module [, member]...
	     Delete the	modules	named by the arguments member from the current
	     archive.

     directory archive (member [, member]...) [outputfile]
	     List each named module in the archive.  The format	of the output
	     depends on	the verbosity setting set using	the verbose command.
	     Output is sent to standard	output,	or to the file specified by
	     argument outputfile.

     end     Exit successfully from the	ar utility.  Any unsaved changes to
	     the current archive will be discarded.

     extract member [, member]...
	     Extract the members named by the arguments	member from the	cur-
	     rent archive.

     list    Display the contents of the current archive in verbose style.

     open archive
	     Open the archive named by argument	archive	and make it the	cur-
	     rent archive.

     replace member [, member]...
	     Replace named members in the current archive with the files spec-
	     ified by arguments	member.	 The files must	be present in the cur-
	     rent directory and	the named modules must already exist in	the
	     current archive.

     save    Commit all	changes	to the current archive.

     verbose
	     Toggle the	verbosity of the directory command.

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

     To	create a new archive ex.a containing the files ex1.o, and ex2.o, using
     MRI librarian commands, use the following script:

	   create ex.a		    * specify the output archive
	   addmod ex1.o	ex2.o	    * add modules
	   save			    * save pending changes
	   end			    * exit the utility

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)

STANDARDS COMPLIANCE
     The ar utility's support for the -a, -b, -c, -i, -m, -p, -q, -r, -s, -t,
     -u, -v, -C	and -T options is believed to be compliant with	IEEE Std
     1003.2 ("POSIX.2").

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 Reading and
     Writing Streaming Archives	Library	(libarchive, -larchive)	and the	ELF
     Access Library (libelf, -lelf).

BSD				 June 16, 2016				   BSD

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

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ranlib&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help