NAME

pax − portable archive exchange

SYNOPSIS

pax [-cimopuvy] [-f archive] [-s replstr] [-t device] [pattern ...]
pax -r [-cimnopuvy] [-f archive] [-s replstr] [-t device] [pattern ...]
pax -w [-adimuvy] [-b blocking] [-f archive] [-s replstr] [-t device] [-x format] [pathname ...]
pax -rw [-ilmopuvy] [-s replstr] [pathname ...] directory

DESCRIPTION

pax reads and writes archive files that conform to the Archive/Interchange File Format specified in IEEE Std. 1003.1-1988. pax can also read, but not write, a number of other file formats in addition to those specified in the Archive/Interchange File Format description.  Support for these traditional file formats, such as Version 7 tar and System V binary cpio -format archives, is provided for backward compatibility and to maximize portability. 

Read/Write Options

Combinations of the -r and -w command-line options specify whether pax should read, write, or list the contents of the specified archive, or move the specified files to another directory as follows:

-w Write files and directories specified by pathname operands to the standard output together with the pathname and status information prescribed by the archive format used.  If pathname is a directory, pathname refers to the files and (recursively) subdirectories of that directory.  If pathname is not specified, standard input is read to get a list of pathnames to copy, one pathname per line.  In this case, only those pathnames appearing on the standard input are copied. 

-r Read an archive file from the standard input.  Only files whose names match any of the pattern operands are selected for extraction.  Selected files are conditionally created and copied, relative to the current directory tree and subject to the options described below.  By default, the owner and group of selected files is that of the invoking process.  Permissions and modification times are the same as those in the archive. 

Supported archive formats are automatically detected on input.  The default output format is ustar, but can be overridden by the -x format option described below. 

-rw Read the files and directories named in pathname and copy them to the destination directory. If pathname is a directory, pathname refers to the files and (recursively) subdirectories of that directory.  If pathname is not specified, standard input is read to get a list of pathnames to copy, one pathname per line.  In this case, only those pathnames appearing on the standard input are copied.  The directory named by directory must exist and have the proper permissions before the copy can occur. 

If neither the -r or -w options are given, pax lists the contents of the specified archive.  In this mode, pax lists normal files; one per line, hard-link pathnames as

pathname == linkname

and symbolic link pathnames as

pathname -> linkname

where pathname is the name of the file being extracted, and linkname is the name of a file that appeared earlier in the archive. 

If the -v option is specified, pax lists normal pathnames in the same format used by the ls command with the -l option.  Hard links are shown as

<ls −l listing> == linkname

and symbolic links are shown as

<ls −l listing> -> linkname

pax is capable of reading and writing archives that span multiple physical volumes.  Upon detecting an end-of-medium on an archive not yet completed, pax prompts the user for the next volume of the archive, and allows the user to specify the location of the next volume. 

Other Options

pax recognizes the following additional options:

-a Files specified by pathname are appended to the specified archive. 

-b blocking Block the output at blocking bytes per write to the archive file.  A k suffix multiplies blocking by 1024, a b suffix multiplies blocking by 512 and an m suffix multiplies blocking by 1048576 (1 megabyte).  If not specified, blocking is automatically determined on input and is ignored for -rw. 

-c Complement the match sense of the pattern operands. 

-d Intermediate directories not explicitly listed in the archive are not created.  This option is ignored unless -r is specified. 

-f archive archive specifies the pathname of the input or output archive, overriding the default of standard input for -r or standard output for -w. 

-H Search hidden subdirectories (context dependent files or CDF s).  Normally, only the CDF element matching the current context is backed up, without expanding the path name to show the actual element.  For more information on CDF s, see cdf(4).

-i Interactively rename files.  Substitutions specified by -s options (described below) are performed before requesting the new file name from the user.  A file is skipped if an empty line is entered and pax exits with an exit status of 0 if end-of-file is encountered. 

-l Files are linked rather than copied when possible. 

-m File modification times are not preserved. 

-n When -r is specified, but -w is not, pattern arguments are treated as ordinary file names.  Only the first occurrence of each of these files in the input archive is read.  pax exits with a zero exit status after all files in the list have been read.  If one or more files in the list is not found, pax writes a diagnostic to standard error for each of the files and exits with a non-zero exit status.  File names are compared before any of the -i, -s, or -y options are applied. 

-o Restore file ownership as specified in the archive.  The invoking process must have appropriate privileges to accomplish this. 

-p Preserve access time of the input files after they have been copied. 

-s replstr File names are modified according to the substitution expression using the syntax of ed(1) as shown:

-s/old/new/ [gp]

Any non-null character can be used as a delimiter (a / is used here as an example).  Multiple -s expressions can be specified; the expressions are applied in the order specified terminating with the first successful substitution.  The optional trailing p causes successful mappings to be listed on standard error.  The optional trailing g causes the old expression to be replaced each time it occurs in the source string.  Files that substitute to an empty string are ignored both on input and output. 

-t device device is an implementation-defined identifier that names the input or output archive device, overriding the default of standard input for -r and standard output for -w. 

-u Copy each file only if it is newer than an existing file with the same name.  This implies -a. 

-v List file names as they are encountered.  Produces a verbose table of contents listing on the standard output when both -r and -w are omitted; otherwise the file names are printed to standard error as they are encountered in the archive. 

-x format Specifies the output archive format. The input format, which must be one of the following, is automatically determined when -r is used.  The supported formats are:

cpio Extended CPIO interchange format specified in Extended CPIO Format in IEEE Std. 1003.1-1988.

ustar Extended TAR interchange format specified in Extended TAR Format in IEEE Std. 1003.1-1988. This is the default archive format.

-y Interactively prompt for the disposition of each file.  Substitutions specified by -s options (described above) are performed before prompting the user for disposition.  End-of-file or an input line starting with the character q causes pax to exit.  Otherwise, an input line starting with anything other than y causes the file to be ignored.  This option cannot be used in conjunction with the -i option. 

Only the last of multiple -f or -t options is used. 

When writing to an archive, standard input is used as a list of pathnames if pathname is not specified.  The format is one pathname per line.  Otherwise, the standard input is the archive file, which is formatted according to one of the specifications in Archive/Interchange File format in IEEE Std. 1003.1-1988, or some other implementation-defined format.

The user ID and group ID of the process, together with the appropriate privileges, affect the ability of pax to restore ownership and permissions attributes of the archived files.  (See format-reading utility in Archive/Interchange File Format in IEEE Std. 1003.1-1988.)

The -a, -c, -d, -i, -l, -p, -t, -u, and -y options are provided for functional compatibility with the historical cpio and tar utilities.  Option defaults were chosen based on the most common usage of these options.  Therefore, some options have meanings that are different from those of the historical commands. 

Operands

pax recognizes the following operands:

directory The destination directory pathname for copies when both the -r and -w options are specified.  The directory must exist and be writable before the copy or an error results. 

pathname A file whose contents are used instead of the files named on the standard input.  When a directory is named, all of its files and (recursively) subdirectories are copied as well. 

pattern A pattern is given in the standard shell pattern matching notation.  If no pattern is specified, the default is * which selects all files. 

RETURN VALUE

pax exits with one of the following values:

 0 All files in the archive were processed successfully. 

>0 pax aborted due to errors encountered during operation. 

DIAGNOSTICS

If an error occurs, pax terminates immediately without processing any additional files on the command line or in the archive. 

EXAMPLES

Copy the contents of the current directory to tape drive 0:

pax -w -f /dev/rmt0 . 

Copy the contents of olddir to newdir:

mkdir  newdir
cd  olddir
pax -rw . newdir

Read the archive pax.out whose files are all rooted in /usr and extract the archive relative to the current directory:

pax -r -s ’,//*usr//*,,’ -f pax.out

WARNINGS

Special permissions may be required to copy or extract special files. 

Device, user ID, and group ID numbers larger than 65535 cause additional header records to be output. These records are ignored by some historical versions of cpio(1) and tar(1).

The archive formats described in Archive/Interchange File Format have certain restrictions that have been carried over from historical usage.  For example, there are restrictions on the length of pathnames stored in the archive. 

When getting a listing in ls -l style tar-format archives, link counts are listed as zero because the ustar archive format does not keep link count information. 

AUTHOR

pax was developed by Mark H. Colburn and HP. 

FILES

/dev/tty used to prompt user for information when -i or -y options are specified. 

SEE ALSO

cpio(1), find(1), tar(1), cpio(5), tar(5). 

STANDARDS CONFORMANCE

pax: POSIX.2

Hewlett-Packard Company  —  HP-UX Release 9.0: August 1992