unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 ar(1)								       ar(1)




 NAME
      ar - create and maintain portable archives and libraries

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

 DESCRIPTION
      The ar 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 ar consist
      of printable 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 ar creates an archive, it creates headers in a format that
      is portable 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 ar 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 ar is used to create or update the contents of an archive,
      the symbol table is rebuilt (unless the z modifier is used).  The s
      modifier described below forces the symbol table to be rebuilt.

      One key operation character from the set, drqtpmx, 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 abcfFilsuvzACT.  posname is used with the r and m key
      operations and the a, b, and i 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:

	   d	Delete the named files from the archive file.

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

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

		+  If an optional positioning character from the set abi is
		   used, the posname argument must be present and specifies
		   that new files are to be placed after (a) or before (b or
		   i) posname.	In the absence of a positioning character,
		   new files are placed at the end.



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 ar(1)								       ar(1)




		+  ar creates afile if it does not already exist.

		+  If no name is specified and:

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

		   +  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 u modifier is also specified.

	   q	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.	 ar creates afile if it does not
		already exist.

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

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

	   m	Move the named files.  By default, the files are moved to
		the end of the archive.	 If a positioning character is
		present, the posname argument must be present and, as in the
		r 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.

	   x	Extract the named files.  If no names are given, all files
		in the archive are extracted.  In neither case does x alter
		entries from the archive file.

      The following list describes the optional modifier characters:

	   a	Position the files after the existing positioning file
		specified by posname .

	   b	Place the new files before the existing positioning file
		specified by posname .





 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 ar(1)								       ar(1)




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

	   f	Truncate the named file names to 14 bytes before performing
		operations on an archive.  This modifier has been provided
		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 r operation, the first
		existing file that matches the truncated file name is
		replaced.  The f modifier can also be used with other
		operations to allow the full file names to be specified,
		rather than the truncated file names. Also see the
		description of the F modifier.

	   i	Place the new files before the existing positioning file
		specified by posname . Identical to the b modifier.

	   l	Place temporary files in the local current working directory
		rather than in the directory specified by the environment
		variable TMPDIR or in the default directory /var/tmp.  Only
		the d, m, q, and r operations and the s and F modifiers use
		temporary files.

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

	   u	Update the archive.  (r operations only) Do not copy the
		local file to the archive unless the local file is newer
		than the corresponding existing file in the archive.

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

	   z	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 z
		modifier will cause it to be invalidated.  If a file name



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 ar(1)								       ar(1)




		longer than 15 bytes is given the entire archive is
		rewritten.  To rebuild the symbol table, either use the
		ranlib command (see ranlib(1)), or invoke ar again with the
		s modifier.

	   A	Suppress warning messages regarding optional access control
		list entries.  ar 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.

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

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

	   T	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 T modifier
		can only be used with the x operation.

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

	   d:	v, f, F, l
	   m:	v, f, F, l, and a | b | i
	   r:	v, f, F, l, c, A, u, and a | b | i
	   q:	v, f, F, l, c, A, z, s
	   t:	v, f, F, s
	   p:	v, f, F, s
	   x:	v, f, F, s, C, T

 EXTERNAL INFLUENCES
    Environment Variables
      The following internationalization variables affect the execution of
      ar:

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




 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 ar(1)								       ar(1)




      LC_ALL
	   Determines the values for all locale categories and has
	   precedence over LANG and other LC_* environment variables.

      LC_CTYPE
	   Determines the locale category for character handling functions.

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

      LC_NUMERIC
	   Determines the locale category for numeric formatting.

      LC_TIME
	   Determines the format and contents of date and time formatting.

      NLSPATH
	   Determines the location of message catalogues for the processing
	   of LC_MESSAGES.

      If any internationalization variable contains an invalid setting, ar
      behaves as if all internationalization variables are set to C.  See
      environ(5).

      In addition, the following environment variable affects ar:

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

 DIAGNOSTICS
      phase error on file name
		     The named file was modified by another process while ar
		     was copying it into the archive.  When this happens, ar
		     exits and the original archive is left untouched.

      ar write error:  file system error message
		     ar could not write to a temporary file or the final
		     output file.  If ar was trying to write the final
		     output file, the original archive is lost.

      ar reports cannot create file.a, where file.a is an ar-format archive
      file, even if file.a already exists.  This message is triggered when
      file.a 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:




 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000






 ar(1)								       ar(1)




	   ar r newlib.a f3 f2 f1 f4

      Replace files f2 and f3 such that the new copies follow file f1, and
      f3 follows f2:

	   ar ma f1 newlib.a f2 f3
	   ar ma f2 newlib.a f3
	   ar r newlib.a f2 f3

      The archive is then ordered:

	   newlib.a:  f1 f2' f3' f4

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

	   f1 f3 f2 f4

      Note that the relative order of f2 and f3 has not changed.  The second
      command says "move f3 after f2 in newlib.a", creating the order:

	   f1 f2 f3 f4

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

	   ar ra f1 newlib.a f2 f3

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

	   newlib.a:  f3' f2' f1 f4

 WARNINGS
      If you are a user who has appropriate privileges, ar 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, ar matches the first
      occurrence of the file in the archive.

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



 Hewlett-Packard Company	    - 6 -   HP-UX Release 11i: November 2000






 ar(1)								       ar(1)




 FILES
      /var/tmp/ar*	       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
			archive 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:
      HP-UX Linker and Libraries Online User Guide
			(See the +help option)
      HP-UX Linker and Libraries User's Guide
			(See manuals(5) for ordering information)

 STANDARDS CONFORMANCE
      ar: SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2




























 Hewlett-Packard Company	    - 7 -   HP-UX Release 11i: November 2000