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
       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 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 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 cre-
       ate 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 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 cor-
			responding member files are replaced.

		     o	If an optional positioning character from the set is used, the posname argument must be present  and  specifies  that  new
			files are to be placed after or before or posname.  In the absence of a positioning character, 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 speci-
			   fied.

	      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 archive.  If a positioning character is present, the posname argument must
		     be present and, as in the operation, posname specifies where the files are to be moved.  Note that, when used  with  a  posi-
		     tioning  character,  the files are moved in the same order that they currently appear in the archive, not in the order speci-
		     fied 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 specified 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 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 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 specified, rather than the truncated file names. Also see the description of the modifier.

	      Place the new files before the existing positioning file specified 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 operations and
		     the and modifiers use temporary files.

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

	      Update the archive.
		     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.

	      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 infor-
		     mation 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 modifier 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 modifier.

	      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 pro-
		     vided  for  compatibility	with  previous releases where file names up to a maximum of 14 bytes were supported.  Also see the
		     description of the modifier.

	      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 original archive is lost.

       reports , where is an archive file, even if already exists.  This message 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 command 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 sim-
       ply 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 generation
       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 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:
       (See the 	 option)
       (See		 manuals(5) for ordering information)

STANDARDS CONFORMANCE

																	     ar(1)