unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



pax(1)								       pax(1)



NAME

  pax -	Extracts, writes, and lists archive files

SYNOPSIS

  Listing Member Files of Archived Files


  pax [-cdnv] [-f archive] [-s replacement_string]... [pattern...]

  Extracting Archive Files


  pax -r  [-cdiknuvyz] [-f archive] [-p	string]... [-s replacement_string]...
  [pattern...]

  Writing Archive Files


  pax -w  [-adituvVXy] [-b blocksize] [-f archive] [-s replacement_string]...
  [-x format] [file...]

  Copying Files


  pax -r  -w  [-diklntuvVXy] [-p string]... [-s	replacement_string]...
  [file...] directory

  The pax command extracts, writes, and	lists members of archive files.	 It
  also copies files and	directory hierarchies.

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  pax:	XCU5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

OPTIONS

  -a  Appends files to the end of the archive.	Certain	devices	might not
      support appending.

  -b blocksize
      Specifies	the block size for output to be	the positive decimal integer
      of bytes specified by the	blocksize argument. The	block size value can-
      not exceed 32,256, the maximum size for POSIX portability.  Blocking is
      automatically determined on input.

  -c  Matches all file or archive members except those specified by the	pat-
      tern or file arguments.

  -d  Causes directories being copied or archived, or archived directories
      being extracted, to match	only the directory or archived directory
      itself and not the contents of the directory or archived directory.

  -f archive
      Specifies	the path of an archive file to be used instead of standard
      input (when the -w option	is not specified) or the standard output
      (when the	-w option is specified but the -r option is not). When speci-
      fied with	the -a option, any files written to the	archive	are appended
      to the end of the	archive.

  -i  Interactively renames files or archives interactively. For each archive
      member that matches the pattern argument or file that matches a file
      argument,	a prompt is written to the terminal (/dev/tty) that contains
      the name of a file or archive member. A line is then read	from the ter-
      minal. If	this line is empty, the	file or	archive	member is skipped.
      If this line consists of a dot, the file or archive member is processed
      with no modification to its name.	Otherwise, its name is replaced	with
      the contents of the line.	 The pax command immediately exits with	a
      nonzero exit status if an	End-of-File is encountered when	reading	a
      response or if it	cannot read or write to	the terminal.

  -k  Prevents the pax command from writing over existing files.

  -l  Links files when copying files.  When both -r and	-w are specified,
      hard links are established between the source and	destination file
      hierarchies whenever possible.

  -n  Selects the first	archive	member that matches each pattern argument.
      No more than one archive member is matched for each pattern (although
      members of type directory	will still match the file hierarchy rooted at
      that file).

  -p string
      Specifies	one or more file characteristics to be retained	or discarded
      on extraction. The string	argument consists of the characters a, e, m,
      o, and p.	Multiple characteristics can be	concatenated within the	same
      string and multiple -p options can be specified.	The specification
      flags have the following meanings:

      a	  Does not retain file-access times.

      e	  Retains the user ID, group ID, access	permission, access time, and
	  modification time.

      m	  Does not retain file-modification times.

      o	  Retains the user ID and the group ID.

      p	  Retains the access permission.

      Retain means that	an attribute stored in the archive is given to the
      extracted	file, subject to the permissions of the	invoking process;
      otherwise, the attribute is determined as	part of	the normal file	crea-
      tion action.

      If neither the e nor the o flag is specified, or the user	ID and group
      ID are not retained, the pax command does	not set	the S_ISUID and
      S_ISGID bits of the access permission. If	the retention of any of	these
      items fails, the pax command writes a diagnostic message to standard
      error. Failure to	retain any of the items	affects	the exit status, but
      does not cause the extracted file	to be deleted. If specification	flags
      are duplicated or	conflict with each other, the ones given last take
      precedence. For example, if -p eme is specified, file-modification
      times are	retained.

  -r  Reads an archive file and	any associated extended	attributes from	the
      standard input.

  -s replacement_string
      Modifies file-member or archive-member names specified by	the pattern
      or file arguments	according to the substitution expression
      replacement_string, using	the syntax of the ed command. The substitu-
      tion expression has the following	format:

      -s /old/new/ [gp]

      In the ed	command, old is	a basic	regular	expression and new can con-
      tain an &&	(ampersand), \n	(n is a	digit) back references,	or subexpres-
      sion matching. The old string can	also contain newline characters.

      Any nonnull character can	be used	as a delimiter.	The slash (/) charac-
      ter is the delimiter in the previous format). Multiple -s	option
      expressions can be specified; the	expressions are	applied	in the order
      specified, terminating with the first successful substitution.  The
      optional trailing	g character performs as	in the ed command. The
      optional trailing	p character causes successful substitutions to be
      written to the standard error. File-member or archive-member names that
      substitute to the	empty string are ignored when reading and writing
      archives.

  -t  Causes the access	times of the archived files to be the same as they
      were before being	read by	the pax	command.

  -u  Ignores files that are older (having a less recent file modification
      time) than a preexisting file or archive member with the same name.

      When extracting files (-r	option), an archive member with	the same name
      as a file	in the file system is extracted	if the archive member is
      newer than the file.

      When writing files to an archive file (-w	option), an archive member
      with the same name as a file in the file system is superseded if the
      file is newer than the archive member.

      When copying files to a destination directory (-rw options), the file
      in the destination hierarchy is replaced by the file in the source
      hierarchy	or by a	link to	the file in the	source hierarchy if the	file
      in the source hierarchy is newer.

  -v  Writes information about the process. If neither the -r or -w options
      are specified, the -v option produces a verbose table of contents	that
      resembles	the output of ls -l; otherwise,	archive-member pathnames are
      written to standard error.

  -V  [Tru64 UNIX]  Prevents any extended attributes from being	archived with
      associated files.	 This option is	particularly useful for	archiving
      files that are to	be restored with previous versions of tar and cpio.

  -w  [Tru64 UNIX]  Writes files and any extended attributes to	the standard
      output in	the specified archive format.

  -x format
      Specifies	the output archive format. The pax command recognizes the
      following	formats:

      cpio
	  Extended cpio	interchange format. The	default	blocking value for
	  this format for character special archive files is 5120. Blocking
	  values from 512 to 32,256 in increments of 512 are supported.

      xtar
	  Extended tar interchange format.  The	default	blocking value for
	  this format for character special archive files is 10240.  Blocking
	  values from 512 to 32,256 in increments of 512 are supported.	 This
	  option lets the user archive long file names and extended UID/GID
	  values.

      ustar
	  Extended tar interchange format.  This is the	default	output
	  archive format.  The default blocking	value for this format for
	  character special archive files is 10240. Blocking values from 512
	  to 32,256 in increments of 512 are supported.

      Any attempt to append to an archive file in a format different from the
      existing archive format causes the pax command to	exit immediately with
      a	nonzero	exit status.

  -X  When traversing the file hierarchy specified by a	pathname, the pax
      command does not descend into directories	that have a different device
      ID.

  -y  [Tru64 UNIX]  Prompts interactively for the disposition of each file.
      Substitutions specified by the -s	option are performed before you	are
      prompted for disposition.	 An EOF	marker or an input line	starting with
      the character "q"	causes the pax command to exit.	Otherwise, an input
      line starting with anything other	than the character "y" causes the
      file to be ignored.

  z   [Tru64 UNIX]  Positions the tape after the EOF marker on extraction or
      listing.	The z option lets the user extract or list tapes that have
      multiple archives	on them	one after the other without error as a result
      of the tape not being positioned correctly for the next extraction or
      listing.

  Option Interaction and Processing Order


  The options that operate on the names	of files or archive members (-c, -i,
  -n, -s, -u, and -v) interact as follows.

  When extracting files	(-r option), archive members are selected, using the
  modified names, according to the user-specified pattern arguments as modi-
  fied by the -c, -n, and -u options.  Then, any -s and	-i options modify, in
  that order, the names	of the selected	files. The -v option writes the	names
  resulting from these modifications.

  When writing files to	an archive file	(-w option), or	when copying files,
  the files are	selected according to the user-specified pathnames as modi-
  fied by the -n and -u	options.  Then,	any -s and -i options modify, in that
  order, the names resulting from these	modifications.	The -v option writes
  the names resulting from these modifications.

  If both the -u and -n	options	are specified, the pax command does not	con-
  sider	a file selected	unless it is newer than	the file to which it is	com-
  pared.

OPERANDS

  directory
      The destination directory	pathname for copy mode.

  file
      A	pathname of a file to be copied	or archived.

  pattern
      A	pattern	matching one or	more pathnames of archive members. A pattern
      must be given in name-generating notation. The default, if no pattern
      is specified, is to select all members in	the archive.



DESCRIPTION

  The pax command extracts and writes member files and any associated,
  extended attributes of archive files;	writes lists of	the member files of
  archives; and	copies directory hierarchies. The -r and -w options specify
  the archive operation	performed by the pax command.

  The pattern argument specifies a pattern that	matches	one or more paths of
  archive members. A \ (backslash) character is	not recognized in the pattern
  argument and it prevents the subsequent character from having	any special
  meaning. If no pattern argument is specified,	all members are	selected in
  the archive.

  If a pattern argument	is specified, but no archive members are found that
  match	the pattern specified, the pax command detects the error, exits	with
  a nonzero exit status, and writes a diagnostic message.

  The pax command can read both	tar and	cpio archives.	In the case of cpio,
  this means that pax can read ASCII archives (which are created with cpio
  -c) and binary archives (which are created without the -c option).  The
  supported archive formats are	automatically detected on input.

  The pax command can also write archives that tar and cpio can	read; by
  default, pax writes archives in the ustar extended tar interchange format.
  The pax command also writes ASCII cpio archives; use the -x cpio option to
  specify this extended	cpio output format.

  Listing Member Files of Archived Files


  When neither the -r nor the -w options are specified,	the pax	command
  writes the names of the members of the archive file read from	the standard
  input, with pathnames	matching the specified patterns, to the	standard out-
  put. If a named file is a directory, the file	hierarchy contained in the
  directory is also written.  You can specify the pax command without the -r
  or -w	options	with the -c, -d, -f, -n, -s, and -v options, and with the
  pattern argument.

  If neither the -r or -w options are included,	pax lists the contents of the
  specified archive, one file per line.	 The pax command lists hard link
  pathnames as follows:

       pathname	== linkname

  The pax command lists	symbolic link pathnames	as follows:

       pathname	->> linkname

  In both of the preceding cases, pathname is the name of the file that	is
  being	extracted, and linkname	is the name of a file that appeared earlier
  in the archive.

  If the -v option is specified, the listing of	hard link pathnames is output
  in the ls -l command format.






  Extracting Archive Files


  When the -r option is	specified, but the -w option is	not, the pax command
  extracts the members of an archive file and any extended attributes read
  from the standard input, and with pathnames matching the pattern argument
  if one is specified. If an extracted file is a directory, the	file hierar-
  chy contained	in the directory is also extracted. The	extracted files	are
  created relative to the current file hierarchy.  The -r option can be
  specified with the -c, -d, -f, -n, -s, and -v	options, and a pattern argu-
  ment.

  The access and modification times of the extracted files are the same	as
  the archived files. The access permissions of	the extracted files remain as
  archived unless affected by the user's default file creation mode. The
  S_ISUID and S_ISGID bits of the extracted files are cleared.

  If intermediate directories are necessary to extract an archive member, the
  pax command creates the directories with access permissions set as the bit-
  wise inclusive OR of the values of the S_IRWXU, S_IRWXG, and S_IRWXO
  options.

  If the selected archive format supports the specification of linked files
  (both	the tar	and cpio formats do), it is an error if	these files cannot be
  linked when the archive is extracted.	 The pax command informs you of	the
  error	and continues processing.

  Writing Archive Files


  When the -w option is	specified and the -r option is not, the	pax command
  writes the contents of the files and any extended attributes specified by
  the file arguments to	the standard output in an archive format. If no	file
  arguments are	specified, a list of files to copy, one	per line, is read
  from the standard input. When	the file argument specifies a directory, all
  of the files and any extended	attributes contained in	the directory are
  written. The -w option can be	specified with the -b, -d, -f, -i, -s, -t,
  -u, -v, -x, and -X options and with file arguments.

  If -w	is specified, but no files are specified, standard input is used.  If
  neither -f or	-w are specified, standard input must be an archive file.

  Copying Files


  When both the	-r and -w options are specified, the pax command copies	the
  files	and any	extended attributes specified by the file arguments to the
  destination directory	specified by the directory argument. If	no file	argu-
  ments	are specified, a list of files to copy,	one per	line, is read from
  the standard input. If a specified file is a directory, the file hierarchy
  contained in the directory is	also copied. The -r and	-w options can be
  specified with the -d, -i, -k, -l, -p, -n, -s, -t, -u, -v, and -X options
  and with the file arguments. A directory argument must be specified.

  Copied files are the same as if they were written to an archive file and
  subsequently extracted.

NOTES

   1.  [Tru64 UNIX]  When you use the -i option	(interactively renames files)
       on files	to which there are hard	links, pax does	not create hard	links
       to the renamed files.

   2.  [Tru64 UNIX]  Archives created with the new pax utility and having
       cpio format can be restored using only the new pax or cpio commands
       even if none of the archived files have extended	attributes.

   3.  [Tru64 UNIX]  To	achieve	backward compatibility of archived files,
       invoke the -V option to disable the archiving of	extended attributes
       altogether.

   4.  [Tru64 UNIX]  Socket files are ignored while archiving through the pax
       command.

EXIT STATUS

  The following	exit values are	returned:

  0   Successful completion.

  >>0  An error occurred.

EXAMPLES

   1.  To copy the contents of the current directory to	the tape drive,
       enter:
	    pax	-w -f /dev/rmt0	.

   2.  To copy the olddir directory hierarchy to newdir, enter:
	    mkdir newdir
	    (cd	./olddir ; pax -p e -rw	. ../newdir)

   3.  To read the archive a.pax, with all files rooted	in the directory /usr
       in the archive extracted	relative to the	current	directory, enter:
	    pax	-r -s ',^//*usr//*,,' -f a.pax

       All of the preceding examples create archives in	tar format.

       The following pairs of commands demonstrate conversions from cpio and
       tar to pax.  In all cases, the examples show comparable command-line
       usage rather than identical output formats.  The	-x option can be
       specified to the	pax commands shown here, producing archives to select
       specific	output formats:
	    ls * | cpio	-ocv
	    pax	-wdv *

	    find /mydir	-type f	-print | cpio -oc
	    find /mydir	-type f	-print | pax -w

	    cpio -icdum	<&lt; archive
	    pax	-r <&lt; archive

	    (cd	/fromdir;find .	-print)	| cpio -pdlum /todir
	    pax	-rw /fromdir /todir

	    tar	cf archive *
	    pax	-w -f archive *

	    tar	xfv - <&lt;	archive
	    pax	-rv <&lt; archive

	    (cd	/fromdir; tar cf - . ) | (cd /todir; tar xpf -)
	    pax	-rw /fromdir /todir









ENVIRONMENT VARIABLES

  The following	environment variables affect the execution of pax:

  LANG
      Provides a default value for the internationalization variables that
      are unset	or null. If LANG is unset or null, the corresponding value
      from the default locale is used. If any of the internationalization
      variables	contain	an invalid setting, the	utility	behaves	as if none of
      the variables had	been defined.

  LC_ALL
      If set to	a non-empty string value, overrides the	values of all the
      other internationalization variables.

  LC_CTYPE
      Determines the locale for	the interpretation of sequences	of bytes of
      text data	as characters (for example, single-byte	as opposed to multi-
      byte characters in arguments and input files), the behavior of charac-
      ter classes used in the extended regular expressions defined for the
      yesexpr locale keyword in	the LC_MESSAGES	category, and pattern match-
      ing.

  LC_MESSAGES
      Determines the locale for	the format and contents	of diagnostic mes-
      sages written to standard	error.

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

SEE ALSO

  Commands:  cpio(1), ed(1), tar(1)

  Files:  tar(4)

  Standards:  standards(5)