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

FreeBSD Manual Pages

  
 
  

home | help
ar(1)									 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
	      INFLU-
	      ENCES

   Environment	 Vari-
       ables
       The   following
       international-
       ization	 vari-
       ables	affect
       the   execution
       of

       Determines  the
       locale category
       for native lan-
       guage,	 local
       customs and
	      coded
	      charac-
	      ter  set
	      in   the
	      absence
	      of   and
	      other
	      environ-
	      ment
	      vari-
	      ables.
	      If    is
	      not
	      speci-
	      fied  or
	      is   set
	      to   the
	      empty
	      string,
	      a
	      default
	      of  (see
	      lang(5))
	      is  used
	      instead
	      of

       Determines  the
       values for  all
       locale	 cate-
       gories and  has
       precedence over
	      and
	      other
	      environ-
	      ment
	      vari-
	      ables.

       Determines  the
       locale category
       for   character
       handling	 func-
       tions.

       Determines  the
       locale	  that
       should be  used
       to  affect  the
       format
	      and con-
	      tents of
	      diagnos-
	      tic mes-
	      sages
	      written
	      to stan-
	      dard
	      error.

       Determines  the
       locale category
       for     numeric
       formatting.

       Determines  the
       format and con-
       tents  of  date
       and  time  for-
       matting.

       Determines  the
       location	    of
       message	 cata-
       logues  for the
       processing
	      of

       If any interna-
       tionalization
       variable	  con-
       tains	    an
       invalid	  set-
       ting,   behaves
       as    if	   all
       international-
       ization	 vari-
       ables  are  set
       to  See	 envi-
       ron(5).

       In    addition,
       the   following
       environment
       variable
       affects

       Specifies     a
       directory
	      for tem-
	      porary
	      files
	      (see
	      tmp-
	      nam(3S)).
	      The mod-
	      ifier
	      over-
	      rides
	      the
	      vari-
	      able,
	      and
	      over-
	      rides
	      the
	      default
	      direc-
	      tory.

DIAGNOSTICS
       The named  file
       was modified by
       another process
       while
		      was
		      copy-
		      ing
		      it
		      into
		      the
		      ar-
		      chive.
		      When
		      this
		      hap-
		      pens,
		      exits
		      and
		      the
		      orig-
		      i-
		      nal
		      ar-
		      chive
		      is
		      left
		      untouched.

       could not write
       to a  temporary
       file   or   the
       final	output
       file.
		      If
		      was
		      try-
		      ing
		      to
		      write
		      the
		      final
		      out-
		      put
		      file,
		      the
		      orig-
		      i-
		      nal
		      ar-
		      chive
		      is
		      lost.

       reports , where
       is  an  archive
       file,  even  if
       already exists.
       This message is
       triggered  when
       is   write-pro-
       tected or inac-
       cessible.

EXAMPLES
       Create  a   new
       file   (if  one
       does	   not
       already	exist)
       in archive for-
       mat   with  its
       constituents
       entered	in the
       order	 indi-
       cated:

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

       The  archive is
       then ordered:

       where the  sin-
       gle quote marks
       indicate
       updated	files.
       The first  com-
       mand says "move
       and  after   in
       newlib.a", thus
       creating	   the
       order:

       Note  that  the
       relative	 order
       of  and has not
       changed.	   The
       second  command
       says	 "move
       after	    in
       newlib.a", cre-
       ating	   the
       order:

       The third  com-
       mand	  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	 posi-
       tion  and rela-
       tive  order  of
       and  in the ar-
       chive are  pre-
       served (no mat-
       ter   how   the
       files are spec-
       ified  on   the
       command	line),
       producing   the
       following   ar-
       chive:

WARNINGS
       If  you	are  a
       user   who  has
       appropriate
       privileges, can
       alter  any  ar-
       chive	 file,
       even if	it  is
       write-pro-
       tected.

       If   the	  same
       file   is  men-
       tioned 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	occur-
       rence   of  the
       file in the ar-
       chive.

       automatically
       creates an  ar-
       chive	symbol
       table,  a  task
       performed    in
       early	 HP-UX
       versions	by Use
       of the modifier
       either	  sup-
       presses genera-
       tion   of   the
       symbol	table,
       or  invalidates
       it    if	    it
       exists.	   The
       command can  be
       used to rebuild
       the symbol  ta-
       ble  if	an ar-
       chive was built
       with  the modi-
       fier.

FILES
       Temporary
				files

SEE ALSO
   System Tools:
       ld(1)		 Invoke
			 the
			 link
			 edi-
			 tor

   Miscellaneous:
       acl(5)		 Access
			 con-
			 trol
			 lists
       a.out(4)		 Assem-
			 bler,
			 com-
			 piler,
			 and
			 linker
			 out-
			 put
       ar(4)		 Ar-
			 chive
			 for-
			 mat
       lorder(1)	 Find
			 the
			 order-
			 ing
			 rela-
			 tion
			 for
			 object
			 files
			 or
			 ar-
			 chive
			 libraries
       ranlib(1)	 Regen-
			 er-
			 ate
			 an
			 ar-
			 chive
			 sym-
			 bol
			 ta-
			 ble
       strip(1)		 Strip
			 sym-
			 bol
			 and
			 line
			 num-
			 ber
			 infor-
			 ma-
			 tion
			 from
			 an
			 object
			 file
       tmpnam(3S)	 Cre-
			 ate
			 a
			 name
			 for
			 a
			 tem-
			 po-
			 rary
			 file

   Texts  and  Tutori-
       als:
       (See
			 the	      option)
       (See		 man-
			 u-
			 als(5)
			 for
			 order-
			 ing
			 infor-
			 ma-
			 tion)

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