`pax`

Portable archive interchange (POSIX)

Syntax:

List archive contents:

pax [-cimopuvy] [-f archive] [-s replstr]...
    [-t device] [pattern...]

Read an archive:

pax -r [-cimnopuvy] [-f archive] [-s replstr]...
    [-t device] [pattern...]

Write an archive:

pax -w [-dimuvy] [-b blocking] [-[a]f archive] 
    [-s replstr]... [-t device] [-x format]
    [pathname...]

Copy files:

pax -rw [-ilmopuvy] [-s replstr]... [pathname...]
    directory

Options:

-a

Append the files specified by pathname to the archive specified with -f.

-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 (copy files).

-c

Complement the match sense of the pattern operands.

-d

Don't create intermediate directories not explicitly listed in the archive. This option is applied only if the -r option is specified.

-f archive

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

-i

Interactively rename files. Substitutions specified by -s options are performed before requesting the new filename from the user. A file is skipped if an empty line is entered. If EOF is encountered, pax exits with an exit status of 0.

-l

("el") When possible, link rather than copy files.

-m

Don't keep file modification times.

-n

When -r is specified, but -w isn't, treat the pattern operands as ordinary filenames. Only the first occurrence of each of these files in the input archive is read. The pax utility exits with an exit status of 0 after all files in the list have been read. If one or more of the files in the list aren't found, pax writes a diagnostic to standard error for each of these files and exits with a nonzero exit status. The filenames 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 the access time of the input files after they have been copied.

-s replstr

Modify filenames according to the substitution expression. The syntax for the expression is:

-s /old/new/[gp]

Any non-null character may be used as a delimiter (a / is used here as an example). Multiple -s 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

The device argument 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 a preexisting file with the same name.

-v

Be verbose; list filenames as they are encountered. This option produces a table of contents listing on the standard output when both -r and -w are omitted; otherwise the filenames are printed to standard error as they are encountered in the archive.

-x format

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

cpio: The extended cpio interchange format specified in POSIX Std 1003.1-1988.
ustar: The extended tar interchange format, also specified in POSIX 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 the user is prompted for disposition. EOF 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 -f or -t option takes effect.

directory

The destination directory pathname for copies when both the -r and -w options are specified. The directory must exist and you must have the appropriate write permissions, or an error results.

pathname

A file to be copied or a directory containing files and subdirectories to be (recursively) copied in addition to the directory itself.

pattern

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

Modes of operation:

If you don't specify -r or -w, then pax lists the contents of the specified archive. In this mode, pax lists normal files one per line. Hard link pathnames are listed 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.

Symbolic link pathnames are listed as:

pathname -> destination_path

If -v is specified, then pax lists normal pathnames in the same format used by the ls utility with the -l ("el") option, except for hard links which are shown as:

<ls -l listing> == linkname

The modes of operation related to combinations of -r and -w are as follows:

-r: Read an archive file from the standard input; select for extraction only those files whose names match any of the pattern operands. The selected files are conditionally created and copied relative to the current directory tree, subject to the options chosen. By default, the owner and group of selected files are those of the invoking process, and the permissions and modification times are the same as those in the archive.
The supported archive formats are automatically detected on input.
-w: Write the files and directories specified by pathname operands to the standard output, together with the pathname and status information prescribed by the archive format used. The default output format is tar, but may be overridden by the -x format option described below.
A directory pathname operand refers to the files and (recursively) subdirectories of that directory. If no pathname operands are given, then the 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.
-rw: Read the files and directories named in the pathname operands and copy them to the destination directory. A directory pathname operand refers to the files and (recursively) subdirectories of that directory. If no pathname operands are given, the 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 the directory operand must exist and must have the proper permissions before the copy can occur.

Description:

The pax utility reads and writes archive files that conform to the archive/interchange file format specified in POSIX Std 1003.1-1988. The utility can also read, but not write, a number of other file formats. Support for these traditional file formats (such as V7 tar and System V binary cpio format archives) is provided for backward compatibility and to maximize portability.

The pax utility also supports traditional cpio and System V tar interfaces if invoked with those names (they're links to pax).

The pax utility is capable of reading and writing archives that span multiple physical volumes. Upon detecting an end of medium on an archive that isn't yet completed, pax prompts you for the next volume of the archive and lets you specify the location of the next volume.

If the pax archive is stored directly in a floppy disk block special file (e.g. /dev/fd0), the archive overwrites the first block of the disk, which the floppy driver, devb-fdc, uses to store media-type information that lets it dynamically adjust to diskettes of differing media capacity being inserted in the drive (e.g. 720k vs 1.4M, 360k vs 1.2M etc.). If the floppy driver can't determine the capacity, it assumes 1.4M.

Combinations of the -r and -w command-line arguments specify whether pax reads, writes, or lists the contents of the specified archive, or moves the specified files to another directory.

When writing to an archive, the standard input is used as a list of pathnames if no pathname operands are specified. The format is one pathname per line. When reading, the standard input is the archive file, which is formatted according to one of the format specifications in POSIX Std 1003.1-1988.

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 Archive/Interchange File Format in POSIX Std 1003.1-1988.)

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

Examples:

Copy the contents of the current directory to the floppy drive:

    pax -w -f /dev/fd0 .

Copy the contents of olddir to newdir:

    mkdir newdir
    cd olddir
    pax -rw . ../newdir

Read the archive pax.out with all files rooted in /usr in the archive extracted relative to the current directory (not the use of commas as pattern separators for the -s option):

    pax -r -s ",^/usr/,," -f pax.out

Files:

The controlling terminal (/dev/tty) is used to prompt the user for information when the -i or -y options are specified.

Exit status:

0: All files in the archive were processed successfully.
>0: The pax utility aborted due to errors encountered during operation.

Caveats:

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 and tar.

The archive formats described in Archive/Interchange File Format have certain restrictions that have been carried over from historical usage. For example, pathnames stored in the archive can be no more than 255 characters in length.

When getting an ls -l style listing on tar format archives, link counts are listed as zero since the ustar archive format doesn't keep link count information.

On 16-bit architectures, including 16-bit versions of QNX 4., the largest buffer size is 32K-1. This is due, in part, to using integers in the buffer allocation schemes. On many of these machines, however, it isn't possible to allocate blocks of memory larger than 32K.