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

FreeBSD Manual Pages

  
 
  

home | help
AR(1)			    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
       archive.	  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
       archive	symbol	table (see ar(5)) used to speed	up link	editing	opera-
       tions.  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	exist-
       ing 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 ar-
	       guments	file ...  are  added after the archive member named by
	       argument	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 ar-
	       guments file ...	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 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 reproducible when member contents  are  identical.
	       This  option  is	enabled	by default.  If	multiple -D and	-U op-
	       tions are specified on the command line,	the  final  one	 takes
	       precedence.

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

       -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
	       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.

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

       -o      Preserve	the original modification times	of  members  when  ex-
	       tracting	them.

       -p      Write  the  contents  of	the specified archive members named by
	       arguments file ... 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.

       -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
	       updated	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  or-
	       der  of	members	 within	the archive.  If a file	named in argu-
	       ments 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 ex-
	       ists, is	updated	to reflect the new state of the	archive.

       -s      Add  an	archive	symbol table (see ar(5)) to the	archive	speci-
	       fied 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      This option is accepted but ignored.  In	other  implementations
	       of ar, -T creates a "thin" archive.

       -u      Conditionally update the	archive	or extract members.  When used
	       with  the  -r option, files named by arguments file ... 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 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
	       options,	ar gives a file-by-file	 description  of  the  archive
	       modification  being  performed,	which consists of three	white-
	       space separated fields: the option letter, a dash "-", and  the
	       file  name.   When used with the	-r option, ar displays the de-
	       scription 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  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 -t option, ar
	       displays	eight whitespace separated fields:  the	 file  permis-
	       sions  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, ex-
	       tract 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 over-
	       written 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
       commands	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 terminate 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
       command word may	be specified in	either case.  Arguments	may  be	 sepa-
       rated 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
	       arguments member, then those members are	added to  the  current
	       archive.	  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  cur-
	       rent archive.

       directory archive (member [, member]...)	[outputfile]
	       List  each named	module in the archive.	The format of the out-
	       put depends on the verbosity setting set	using the verbose com-
	       mand.  Output is	sent to	standard output, or to the file	speci-
	       fied 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
	       specified by arguments member.  The files must  be  present  in
	       the  current 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, us-
       ing 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
       Streaming Archive Library (libarchive, -larchive) and the  ELF  Parsing
       Library (libelf,	-lelf).

FreeBSD	13.2			January	3, 2022				 AR(1)

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

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

home | help