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

FreeBSD Manual Pages

  
 
  

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

NAME
       ar - create and maintain	portable archives and libraries

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

DESCRIPTION
       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
       (described 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  mentioned	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 table to be rebuilt.

       One key operation character from	 the  set,  is	required  and  can  be
       optionally  preceded  by	a hyphen (The required key operation character
       can be specified	with one or more modifier characters from the set pos-
       name is used with the and key operations	and the	and modifiers to spec-
       ify 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
		     already  in  the  archive.	  creates afile	if it does not
		     already exist.

	      Print a table of contents	of the archive file  to	 the  standard
	      output.
		     If	 no  names  are	 given,	 all  files in the archive are
		     described.	 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
		     extracted.	  In  neither case does	alter entries from the
		     archive file.

       The following list describes the	optional modifier characters:

	      Position the files after the existing positioning	file specified
	      by
		     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-
		     fier.

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

	      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:

	      and
	      and

       EXTERNAL	INFLUENCES

   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
	      of

       If  any	internationalization  variable	contains  an  invalid setting,
       behaves as if all internationalization variables	are set	to  See	 envi-
       ron(5).

       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.

DIAGNOSTICS
       The named file was modified by another process while
		      was copying it into the  archive.	  When	this  happens,
		      exits 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.

EXAMPLES
       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:

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

FILES
       Temporary files

SEE ALSO
   System Tools:
       ld(1)		 Invoke	the link editor

   Miscellaneous:
       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
			 object	file
       tmpnam(3S)	 Create	a name for a temporary file

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

STANDARDS CONFORMANCE
									 ar(1)

NAME | SYNOPSIS | DESCRIPTION | DIAGNOSTICS | EXAMPLES | WARNINGS | FILES | SEE ALSO | STANDARDS CONFORMANCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ar&sektion=1&manpath=HP-UX+11.22>

home | help