pax -- archiver for data interchange and file backup

pax archiver for data interchange and file backup	Command

SYNOPSIS

pax [-cdNnqvz] [-f archive] [-s substitute] ... [pattern ...]

pax -r [-cdHhikNnuvz] [-f archive] [-o options] ... [-p string] ... [-s substitute] ... [-V volpat | -Q] [pattern ...]

pax -w [-dHhiLNqtuvXz] [-b blocksize] [[-a] [-f archive]] [-o options] ... [-s substitute] ... [-V volpat | -Q] [-x format] [pathname ...]

pax -r -w [-diklLNquvX] [-p string] ... [-s substitute] ... [pathname ...] directory

DESCRIPTION

pax reads and writes archive files. An archive file records the contents of files and directories, and can also record such information as file modification dates and owner names (on POSIX-compliant systems). You can, therefore, use a single archive file to transfer a directory structure from one machine to another, or to backup/restore groups of files and directories. pax is designed to provide all of the functionality previously provided by both cpio and tar.

A file stored inside an archive is called a component file; similarly, a directory stored inside an archive is called a component directory. Together, these files and directories make up the components of the archive file.

You can specify the name of the archive file with the -f archive option. If you do not specify -f or neither of -r or -w, the pax read mode assumes the archive file is the standard input, while the pax write mode assumes it is the standard output.

pax can read input archives and write output in cpio and tar formats; see the -x option.

On POSIX-compliant systems, you need appropriate privileges to create block or character special files.

Primary Options

The four forms of the command shown in the synopsis represent the main functions of pax .

If you do not specify either -r or -w, you are in list mode. In the list mode, pax uses the standard output to display the table of contents of an existing archive file. pax only displays information on component files with names that match one of the patterns given on the command line. Patterns are described in a later section of this reference page.

-r: If you specify -r but not -w, you are in read mode. pax -r reads an archive file as input and extracts selected components from the archive. By default, pax -r selects the components using patterns given on the command line. If the archive contains several components with the same name, pax -r extracts each of them in sequence with each new file overwriting the previous one of the same name. If the extracted file is a directory, stored files within that directory are also extracted and placed in the extracted directory. Ownership and permissions of the extracted files are discussed under the -p option.
-w: If you specify -w but not -r, you are in write mode. In write mode, pax writes out an archive file that contains the specified pathnames as a component. If pathname is a directory, pax writes an archive file that contains all the files and subdirectories under that directory. If you do not specify a pathname, pax -w reads the standard input to get a list of path names to select, expecting one path name per line.
-r -w: If you specify both -r and -w, you are in copy mode. In copy mode, pax reads the specified pathnames and copies them to the specified directory. In this case, the given directory must already exist and you must be able to write to that directory. If pathname is a directory, pax -r -w copies all the files and subdirectories under that directory as well as the directory itself. If you do not specify a pathname, pax -r -w reads the standard input to get a list of path names to copy, expecting one path name per line.

Secondary Options

Consult the synopsis lines to determine which of the following additional options can be applied with a particular primary option.

-a

appends specified files/directories to the end of an existing archive. pax does not append to the end of a compressed file or to an archive file of a different format. If the archive doesn't already exist, pax creates it.

-b blocksize

specifies the blocksize in an output operation. Each output operation writes blocksize bytes, where blocksize is an integer appropriate to the output device. If b follows the blocksize number, blocksize is the given number of 512-byte blocks. If k follows the blocksize number, the block size is the given number of 1024-byte blocks. When reading an archive, pax automatically determines the block size. The default blocksize is 10k for tar archives, 5k for cpio archives. The blocksize must be at least 512 bytes for reading.

-c

selects all those files that do not match a pattern given on the command line; this is the opposite of the usual behavior.

-d

does not traverse directories. A pattern matching a directory only extracts the directory itself. When creating an archive, a directory name only stores the directory itself.

-f archive

lets you specify the name of the archive file instead of using the standard input for list and read modes and the standard output for write mode. archive can also be a device name.

-H

creates and reads pax archives that contain extraneous header characters, for compatibility with previous versions of MKS pax. The -H option is only useful when working with cpio archives or pax archives created with the -xcpiob option.

-h

creates and reads pax archives with headers structured in a "little-endian" pattern. This option is only useful when working with cpio archives or pax archives created with the -xcpiob option.

The term "little-endian" refers to the internal ordering of bytes representing numbers, stipulating that the least significant values come first. This is the common standard for PCs, but is contrary to the "big-endian" standard of most UNIX machines.

The default for MKS pax when writing cpiob archives is "big-endian." For example, the 32-bit hexadecimal number 1234, written as a binary cpio header using the -h option, would be stored in "little-endian" order:

34 12

Without the -h option, pax defaults to "big-endian" ordering:

12 34

MKS pax automatically senses the byte ordering of any binary cpio archive header being read, and prints a notification to standard output if byte reversal is present.

-i

lets you rename files as pax works. When extracting, pax displays the name of the component it is about to extract and gives you the chance to specify a name for the extracted file. When archiving, pax displays the name of the file or directory it is about to record in the archive, and lets you specify a different name to be assigned to the component. If you enter . as the name, pax processes the file or directory with no modification to the name. If you just press ENTER, pax skips the file (doesn't extract or archive it). pax terminates if you enter EOF.

If you also specify -s, pax makes the given substitution before displaying the name of the component.

-k

prevents the overwriting of existing files.

-L

follows symbolic links. When you specify this option, pax copies the target of a symbolic link to the archive. Normally, only the symbolic link is copied.

-l

in copy mode, creates links to the original files whenever possible, rather than copying them.

-n

treats any pattern argument as an ordinary path name. pax only selects the first match to the given pattern, even if the archive contains several components with the same name. pax checks the given path names against the archive before applying any renaming from the -i or -s options. pax writes an error message for each specified file that cannot be found in the archive.

-o options

provides information for modifying the algorithm for writing and extracting files that the file format specified with -x uses. Currently, there are no options supported.

-p string

specifies file characteristic options. The string argument is a string specifying file characteristics to be retained or discarded on extraction. string can consist of any combination of the following specification characters:

a: does not preserve file access times.
e: preserves the user ID, group ID, file mode, access time, and modification time.
m: does not preserve file modification times.
o: preserves the user ID and group ID.
p: preserves the file mode.

If a character in string duplicates or conflicts with another character in string, the one given last takes precedence. By default, pax restores modification time only.

-Q

If multi-volume support is not specified with the -V option, pax does not prompt for the next volume upon an end-of-file or a write error.

-q

for read mode only, pax assumes that all created files are text files and extracts them to the local text file format. On systems with fixed-length records, this might mean appending blanks as padding.

On UNIX and POSIX-compliant systems, pax removes all carriage return characters (\r) and retains only the newline (\n) characters.

-r

reads an archive file from standard input.

-s substitute

modifies path names using a substitution command substitute. This is similar to the substitution command of the ed text editor. The full option has the form

-s /regexp/string/[gp]

where regexp is a basic regular expression (see regexp) and string is a string that pax inserts in place of matches for the regular expression. string can contain an ampersand & (standing for the string matching regexp), or \1, \2, and so on (with the meanings defined in regexp for subexpression matching).

Normally, -s only replaces the first match for regexp. A g following the string replaces all matches in the line.

A p following the string prints all successful substitutions on the standard error stream. pax displays a substitution in the format

oldname >> newname

In the previous example of substitution, the slash (/) is used as the character separating parts of substitute; you can use any non-null character instead, but be careful not to use any character that could be a part of the path name checked by pax, unless it is properly escaped.

There may be more than one -s option on the command line. In this case, pax tries the substitutions in the order given. pax stops trying to make these substitutions as soon as it makes its first successful substitution. If the null string replaces a file name, pax ignores that file name on both input and output.

-t

after reading files being archived, resets the access time to that prior to pax's access.

-u

compares component dates to dates of existing files with the same name. In read mode, pax extracts a file only if its modification date is more recent than the modification date on an existing file of the same name. In other words, it doesn't overwrite an existing file if the existing file is newer than the one in the archive.

Similarly, in copy mode, pax does not overwrite an existing file if the existing file is newer than the one being copied.

In write mode, -u checks to see if the file being added has the same name as a file already in the archive. If so, and if the file being added is newer than the one in the archive, pax leaves the old file in the archive and appends the new one at the end. In this case, -u automatically implies -a, which means that pax adds new files to the end of the archive.

-V volpat

provides automatic multi-volume support. pax writes output to files whose names are formatted using volpat. It replaces any occurrence of # in volpat with the current volume number. When you invoke pax with this option, it prints a message requesting the appropriate volume and waits for you to type a carriage return before proceeding with the operation. pax issues a similar message when a write error or read error occurs on the archive; the reasoning is that this kind of error means that pax has reached the end of the volume and is to go on to a new one. An interrupt at this point terminates pax.

-v

in list mode, displays a verbose table of contents; this verbose format shows information about the components in the same format used by the ls command with the -l option. In other modes, this option lists path names on the standard error stream just before beginning to process the files/directories, but after any -i or -s options have had their effect.

-w

writes files to the standard output in the specified archive format.

-X

writes out only those files that are on the same device as their parent directory.

-x format

specifies a format for an output archive. The format argument may be:

cpio: standing for the ASCII format used by the cpio command, described in the cpio command and the cpio file format reference pages.
cpiob: standing for the binary format used by cpio.
tar: standing for the old format of tar files; see the tar command and the tar reference pages.
ustar: standing for the (new) USTAR format used by the tar command.

The default format is ustar.

-z

performs compression. Output is at compression level 5. On input, any compression level up to 9 is acceptable. In addition, -z expands compressed archives on input.

pax uses the gzip format to compress files.

Patterns

Command line patterns behave similarly to the wild card constructs explained in sh, including the fact that wild card characters do not match the slash character (/). For example, the pattern * stands for any string of characters excluding slash characters. A pattern like *.c therefore selects all files with the suffix .c under the current directory.

If you do not specify a pattern on a command line that accepts patterns, pax assumes that all files and directories match. As a result pax acts on the entire contents of the current directory, plus the entire contents of all its subdirectories.

Output

When the -v option is used in list mode, pax produces a verbose table of contents for the archive. The output has the format of the ls command with the -l option, with the addition of the notation

pathname == linkname

indicating that linkname is a hard link for pathname.

EXAMPLES

The following example creates an archive file from all the files under the current directory.

pax -w . >/dir/archive

The following example extracts all the components of an archive file and puts them into the current directory.

pax -r * </dir/archive

The following example locates all the files that have changed in the past week (7 days) and archives them onto a diskette:

find c:/ -mtime 7 | pax -w >a:/archive

DIAGNOSTICS

Possible exit status values are:

0

Successful completion.

1

Failure due to any of the following:

— invalid option

— invalid command line arguments

— out of memory

— compression error

— failure on extraction

— failure on creation

2

A usage error occurred.

pax generates an error message and continues to process files if, when reading an archive, pax cannot extract a file, create a link to a file, or preserve any of the modes, owner, or group of a file, or if, when writing an archive, pax cannot find a particular file. Although pax continues to process files, it returns a status of 1. If any other sort of error occurs, pax terminates immediately without attempting further processing.

If pax cannot create a link to a file, it does not create a second copy of the file.

PORTABILITY

POSIX.2. x/OPEN Portability Guide 4.0.

The -L, -q, -V, and -z options are extensions to the POSIX and XPG standards.

We strongly recommend, however, that you specify tape devices as described under tape in the MKS Toolkit Reference Manual. For example

/dev/mt0

NOTE

When accessing an archive that uses the cpio binary storage method (-x cpiob), pax cannot save files larger than two gigabytes in size in an archive. When storing archives in an ASCII formats, pax cannot save files larger than eight gigabytes in size in an archive. However, other programs that extract files from such archives may be unable to properly extract files larger than two gigabytes and pax issues a warning to that effect when you attempt to save such a file.

The -u option of pax calls the sort utility. To ensure that this option works correctly, you should make certain that the MKS Toolkit sort utility (or one compatible with it) is the first one located by the command search path.