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

FreeBSD Manual Pages


home | help
ar(1)			    General Commands Manual			 ar(1)

       ar - create and maintain	portable archives and libraries

       key [modifier ...] [posname] afile [name	...]

       The  command  maintains	groups of files	combined into a	single archive
       file.  Its main use is to create	and update library files  as  used  by
       the  link editor	(see ld(1)).  It can be	used, however, for any similar
       purpose.	 The magic string and file headers used	by consist  of	print-
       able  ASCII  characters.	 If an archive is composed of printable	files,
       the entire archive is printable.

       Individual files	are inserted without conversion	into the archive file.
       When  creates an	archive, it creates headers in a format	that is	porta-
       ble across all machines.	 See ar(4) for a detailed description  of  the
       portable	 archive  format and structure.	 The archive symbol table (de-
       scribed in ar(4)) is used by the	link editor to search  repeatedly  and
       efficiently through libraries of	object files.  An archive symbol table
       is created and maintained by only when the archive  contains  at	 least
       one object file.	 The archive symbol table is in	a specially named file
       that is always the first	file in	the archive.  This file	is never  men-
       tioned or accessible to the user.  Whenever is used to create or	update
       the contents of an archive, the symbol table  is	 rebuilt  (unless  the
       modifier	 is used).  The	modifier described below forces	the symbol ta-
       ble to be rebuilt.

       One key operation character from	the set, is required and  can  be  op-
       tionally	preceded by a hyphen (The required key operation character can
       be specified with one or	more modifier characters from the set  posname
       is  used	with the and key operations and	the and	modifiers to specify a
       position	in the archive.	 afile is the archive file.  Constituent files
       in the archive file are specified by name arguments.

       The following list describes the	key operation characters:

	      Delete the named files from the archive file.

	      Replace the named	files, or add a	new file to the	archive:

		     o	If  the	 modifier is used with the operation character
			only those files with modification  dates  later  than
			those of the corresponding member files	are replaced.

		     o	If  an	optional positioning character from the	set is
			used, the posname argument must	be present and	speci-
			fies  that  new	files are to be	placed after or	before
			or posname.  In	the absence of a  positioning  charac-
			ter, new files are placed at the end.

		     o	creates	afile if it does not already exist.

		     o	If no name is specified	and:

			o  the	specified archive file does not	exist, creates
			   an empty archive file containing only  the  archive
			   header (see ar(4)).

			o  the	archive	contains one or	more files whose names
			   match names in the current directory, each matching
			   archive file	is replaced by the corresponding local
			   file	without	considering which file	may  be	 newer
			   unless the modifier is also specified.

	      Quickly append the named files to	the end	of the archive file.
		     Positioning  characters  are invalid.  The	operation does
		     not check to determine whether the	added members are  al-
		     ready  in	the archive.  creates afile if it does not al-
		     ready exist.

	      Print a table of contents	of the archive file  to	 the  standard
		     If	 no  names are given, all files	in the archive are de-
		     scribed.  If names	 are  given,  information  about  only
		     those files appears.

	      Print  the named files in	the archive to the standard output. If
	      no names
		     are specified, the	contents of all	files are  printed  in
		     the order that they appear	in the archive.

	      Move the named files.
		     By	 default,  the	files  are moved to the	end of the ar-
		     chive.  If	a positioning character	is present,  the  pos-
		     name  argument  must be present and, as in	the operation,
		     posname specifies where the files are to be moved.	  Note
		     that,  when  used with a positioning character, the files
		     are moved in the same order that they currently appear in
		     the  archive,  not	 in the	order specified	on the command
		     line.  See	EXAMPLES.

	      Extract the named	files.
		     If	no names are given, all	files in the archive  are  ex-
		     tracted.  In neither case does alter entries from the ar-
		     chive file.

       The following list describes the	optional modifier characters:

	      Position the files after the existing positioning	file specified
		     posname .

	      Place  the new files before the existing positioning file	speci-
	      fied by
		     posname .

	      Suppress the message normally produced when
		     afile is created.	For and	operations,  normally  creates
		     afile if it does not already exist.

	      Truncate the named file names to 14 bytes	before performing
		     operations	 on  an	 archive.  This	modifier has been pro-
		     vided for compatibility with previous releases where file
		     names  up to a maximum of 14 bytes	were supported.	Longer
		     file names	were truncated.	 When used with	the operation,
		     the  first	 existing file that matches the	truncated file
		     name is replaced.	The modifier can  also	be  used  with
		     other operations to allow the full	file names to be spec-
		     ified, rather than	the truncated file names. Also see the
		     description of the	modifier.

	      Place  the new files before the existing positioning file	speci-
	      fied by
		     posname .	Identical to the modifier.

	      Place temporary files in the local current working directory
		     rather than in the	directory specified by the environment
		     variable  or in the default directory Only	the and	opera-
		     tions and the and modifiers use temporary files.

	      Regenerate the archive symbol table even if
		     is	not invoked with an operation that  modifies  the  ar-
		     chive  contents.	This  modifier is useful for restoring
		     the archive symbol	table after the	command	has been  used
		     on	 the  archive  (see strip(1)) or after the archive has
		     been modified using the modifier.

	      Update the archive.
		     operations	only) Do not copy the local file  to  the  ar-
		     chive unless the local file is newer than the correspond-
		     ing existing file in the archive.

	      Give a verbose file-by-file description
		     of	the creation or	modification of	an archive file	to the
		     standard  output.	When used with gives a long listing of
		     all information about the files.  When used with  the  or
		     operations, the verbose modifier causes to	print each key
		     operation character and the  file	name  associated  with
		     that operation.  For the operation, shows an if it	adds a
		     new file or an if it replaces an existing one.   For  the
		     operation,	 prints	 the  name of the file to the standard
		     output before the contents	of the file are	printed.

	      Suppress the rebuilding of the symbol table when the archive
		     is	modified.  This	modifier is useful only	to avoid  long
		     build times when creating a large archive piece-by-piece.
		     If	an existing archive contains a symbol table, the modi-
		     fier  will	 cause	it  to be invalidated.	If a file name
		     longer than 15 bytes  is  given  the  entire  archive  is
		     rewritten.	  To  rebuild the symbol table,	either use the
		     command (see ranlib(1)), or invoke	again with  the	 modi-

	      Suppress warning messages	regarding
		     optional  access  control list entries.  does not archive
		     optional access control list entries in a	file's	access
		     control  list  (see acl(5)).  Normally, a warning message
		     is	printed	for each file having optional  access  control
		     list entries.

	      Prevent extracted	files from replacing files with	the same name.
		     The modifier can only be used with	the operation.

	      Truncate the entire archive. The
		     modifier  causes  the entire archive to be	rewritten such
		     that all file names within	the archive are	 truncated  to
		     14	bytes, even when does not modify the archive contents.
		     The long name table will be removed  (see	ar(4)).	  This
		     modifier  has been	provided for compatibility with	previ-
		     ous releases where	file names up to a maximum of 14 bytes
		     were  supported.	Also  see the description of the modi-

	      Truncate file names whose	archive	names are  longer  than	 those
	      supported	by
		     the file system. By default, files	with names longer than
		     those supported by	the file system	will not be  extracted
		     and  will	cause an error.	 The modifier can only be used
		     with the operation.

       Only the	following combinations are meaningful; no other	combination of
       modifiers with operations have any effect on the	operation:



   Environment Variables
       The following internationalization variables affect the execution of

       Determines the locale category for native language, local customs and
	      coded  character	set  in	 the  absence of and other environment
	      variables.  If is	not specified or is set	to the empty string, a
	      default of (see lang(5)) is used instead of

       Determines the values for all locale categories and has precedence over
	      and other	environment variables.

       Determines the locale category for character handling functions.

       Determines the locale that should be used to affect the format
	      and contents of diagnostic messages written to standard error.

       Determines the locale category for numeric formatting.

       Determines the format and contents of date and time formatting.

       Determines the location of message catalogues for the processing

       If  any	internationalization variable contains an invalid setting, be-
       haves as	if all internationalization variables are  set	to  See	 envi-

       In addition, the	following environment variable affects

       Specifies a directory
	      for  temporary  files  (see tmpnam(3S)).	The modifier overrides
	      the variable, and	overrides the default directory.

       The named file was modified by another process while
		      was copying it into the archive.	When this happens, ex-
		      its and the original archive is left untouched.

       could not write to a temporary file or the final	output file.
		      If was trying to write the final output file, the	origi-
		      nal archive is lost.

       reports , where is an archive file, even	if already exists.  This  mes-
       sage is triggered when is write-protected or inaccessible.

       Create  a  new  file  (if one does not already exist) in	archive	format
       with its	constituents entered in	the order indicated:

       Replace files and such that the new copies follow file and follows

       The archive is then ordered:

       where the single	quote marks indicate updated files.  The first command
       says "move and after in newlib.a", thus creating	the order:

       Note  that  the relative	order of and has not changed.  The second com-
       mand says "move after in	newlib.a", creating the	order:

       The third command then replaces files and Since files and both  already
       existed	in  the	archive, this sequence of commands could not be	simply
       replaced	by:

       because the previous position and relative order	of and in the  archive
       are  preserved  (no  matter  how	the files are specified	on the command
       line), producing	the following archive:

       If you are a user who has appropriate privileges, can alter any archive
       file, even if it	is write-protected.

       If  the	same  file is mentioned	twice in an argument list, it might be
       put in the archive twice.

       If multiple copies of a file exist in an	archive, matches the first oc-
       currence	of the file in the archive.

       automatically  creates  an  archive  symbol  table, a task performed in
       early HP-UX versions by Use of the modifier either  suppresses  genera-
       tion  of	 the symbol table, or invalidates it if	it exists. The command
       can be used to rebuild the symbol table if an archive  was  built  with
       the modifier.

       Temporary files

   System Tools:
       ld(1)		 Invoke	the link editor

       acl(5)		 Access	control	lists
       a.out(4)		 Assembler, compiler, and linker output
       ar(4)		 Archive format
       lorder(1)	 Find  the  ordering  relation for object files	or ar-
			 chive libraries
       ranlib(1)	 Regenerate an archive symbol table
       strip(1)		 Strip symbol and line number information from an  ob-
			 ject file
       tmpnam(3S)	 Create	a name for a temporary file

   Texts and Tutorials:
       (See the		 option)
       (See		 manuals(5) for	ordering information)



Want to link to this manual page? Use this URL:

home | help