pax(C)

Syntax

pax -r [ -cdikmnTuvy ] [ -f archive ] [ -o options ] ... [ -p string ] ... [ -s replstr ] ... [ pattern ... ]

pax -w [ -diLmtuvXy ] [ -b blocking ] [ [ -a ] [ -f archive ] ] [ -o options ] ... [ -s replstr ] ... [ -x format ] [ pathname ... ]

pax -rw [ -idklLmntuvXy ] [ -p string ] ... [ -s replstr ] ... [ pathname ... ] directory

Description

pax will also support traditional cpio and System V tar interfaces if invoked with the name ``cpio'' or ``tar'' respectively. See the cpio(C) or tar(C) manual pages for more details.

Combinations of the -r and -w command line arguments specify whether pax will read, write or list the contents of the specified archive, or move the specified files to another directory.

The command line arguments are:

-r

pax reads an archive file from the standard input. Only files with names that match any of the pattern operands are selected for extraction. The selected files are conditionally created and copied relative to the current directory tree, subject to the options described below. By default, the owner and group of selected files will be that of the invoking process, and the permissions and modification times will be the same as those in the archive.

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

-w

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

pax reads the files and directories named in the pathname operands and copies 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 have the proper permissions before the copy can occur.

and symbolic link pathnames (if supported by the filesystem) as

pathname -> linkname

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

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

<ls -l listing> == linkname

and symbolic links (if supported) are shown as

<ls -l listing> -> linkname

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

Options

-a

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

-f archive

The -f archive option specifies the pathname of the input or output archive, overriding the default of standard input for -r or standard output for -w. Only the last of multiple -f options takes effect.

-i

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

-k

Prevent the overwriting of existing files.

-l

When specified with the -rw option, link files rather than copy them.

-L

Follow symbolic links.

-m

File modification times are not retained.

-n

Read the first occurrence of the file in the input archive that matches pattern.

-o options

Provide options for the archive format specified by the -x option.

-p string

Specify a string representing characteristics for a file being extracted from an archive. The string is constructed by concatenating any of the following characters:

a

Do not retain file access times.

e

Retain all file characteristics (access and modification times, user and group IDs, and file-mode bits).

m

Do not retain file modification times.

o

Retain user and group IDs.

p

Retain the file-mode bits.

-s replstr

Filenames are modified according to the substitution expression using the syntax of ed(C) as shown:

-s /old/new/[gp]

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

Set the access times of the archived files to be the same as before pax read them.

-T

Truncate long filenames to 14 characters when restoring an archive. This feature is for compatibility with XENIX and AFS filesystems which do not support long filenames. This option is not used with the -w option.

-u

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

-v

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

-x format

Specifies the 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 ``Extended CPIO Format'' in IEEE Std. 1003.1-1988..

ustar

The extended tar interchange format specified in ``Extended TAR Format'' in IEEE Std. 1003.1-1988. This is the default archive format.

The default blocksize for the supported formats is 512 bytes; blocksizes are supported in 512-byte multiples up to 32 kilobytes.

-X

Prevent examination of directories in another filesystem mounted in the directory hierarchy below pathname.

-y

Interactively prompt for the disposition of each file. Substitutions specified by -s options (described above) are performed before prompting the user for disposition. EOF or an input line starting with the character q caused 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.

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 options -a, -c, -d, -i, -l, -u, 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, therefore, some of the options have meanings different than those of the historical commands.

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 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. The default if no pattern is specified is ``''\, which selects all files.

Exit values

pax will exit with one of the following values:

0

All files in the archive were processed successfully.

>0

pax aborted due to errors encountered during operation.

Examples

The following commands copy the contents of olddir to newdir:

mkdir newdir

cd olddir

pax -rw  .  newdir

The command pax -r -s ',^/usr/,\./,' -f pax.out reads the archive pax.out with all files rooted in /usr in the archive extracted relative to the current directory.

Limitations

The archive formats 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 an ls -l style listing on tar format archives, link counts are listed as zero since the ustar archive format does not keep link count information. Root user permissions may be required to copy or extract special files.

Files

/dev/tty

used to prompt the user for information when the -i or -y options are specified

Copyright

Redistribution and use in source and binary forms are permitted provided that the above copyright notice is duplicated in all such forms and that any documentation, advertising materials, and other materials related to such distribution and use acknowledge that the software was developed by Mark H. Colburn and sponsored by The USENIX Association.

THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

Author

Sponsored by The USENIX Association for public distribution.

See also

Standards conformance

ISO/IEC DIS 99452:1992, Information technology Portable Operating System Interface (POSIX) Part 2: Shell and Utilities (IEEE Std 1003.21992);
X/Open CAE Specification, Commands and Utilities, Issue 4, 1992.

Notices