pax Command

AIX Version 4.3 Commands Reference, Volume 4

pax Command

Purpose

Extracts, writes, and lists members of archive files; copies files and directory hierarchies.

Syntax

To List Member Files of Archived Files

pax [ -c ] [ -d ] [ -n ] [ -v ] [ -f Archive ] [ -s ReplacementString ... ] [ -o Options ] [ Pattern ... ]

To Extract Archive Files Using the -r Flag

pax -r [ -c ] [ -d ] [ -i ] [ -k ] [ -n ] [ -u ] [ -v ] [ -y ] [ -f Archive ] [ -o Options ] [ -p String ... ] [ -s ReplacementString ... ] [ Pattern ... ]

To Write Archive Files Using the -w Flag

pax -w [ -d ] [ -i ] [ -t ] [ -u ] [ -v ] [ -X ] [ -y ] [ -b Blocking ] [ [ -a ] -f Archive ] [ -o Options ] [ -s ReplacementString ... ] [ -x Format ] [ File ... ]

To Copy Files Using the -r and -w Flags

pax -r -w [ -d ] [ -i ] [ -k ] [ -l ] [ -n ] [ -t ] [ -u ] [ -v ] [ -X ] [ -y ] [ -p String ... ] [ -o Options ] [ -s ReplacementString ... ] [ File ... ] Directory

Description

The pax command extracts and writes member files of archive files; writes lists of the member files of archives; and copies directory hierarchies. The -r and -w flags specify the type of archive operation.

Listing Member Files of Archived Files

When neither the -r nor the -w flags are specified, the pax command lists all the member files of the archive file read from standard input. If the Pattern parameter is specified, only the member files with path names that match the specified patterns are written to standard output. If a named file is a directory, the file hierarchy contained in the directory is also written. When neither the -r or -w flags are specified, the -c, -d, -f, -n, -s, and -v flags, and the Pattern parameter may be specified.

Extracting Archive Files Using the -r Flag

When the -r flag is specified, but the -w flag is not, the pax command extracts all the member files of the archive files read from standard input. If the Pattern parameter is specified, only the member files with path names that match the specified patterns are written to standard output. If a named file is a directory, the file hierarchy contained in the directory is also extracted. The -r flag can be specified with the -c, -d, -f, -i, -k, -n, -s, -u, -v and -y flags, and with the Pattern parameter.

The access and modification times of the extracted files are the same as the archived files. The file modes of the extracted files are the same as when they were archived, unless they are affected by the user's default file creation mode (umask). 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 bitwise inclusive OR of the values of the S_IRWXU, S_IRWXG, and S_IRWXO masks.

If the selected archive format supports the specification of linked files, it is an error if these files cannot be linked when the archive is extracted.

Writing Archive Files Using the -w Flag

When the -w flag is specified and the -r flag is not, the pax command writes the contents of the files specified by the File parameter to standard output in an archive format. If no File parameter are specified, a list of files to copy, one per line, is read from the standard input. When the File parameter specifies a directory, all of the files contained in the directory are written. The -w flag can be specified with the -a, -b, -d, -f, -i, -o, -s, -t, -u, -v, -x, -X, and -y flags and with File parameters.

When specifying path names that are greater than 100 characters for the United States Tape Archiver (USTAR) format, remember that the path name is composed of a prefix buffer, a / (slash), and a name buffer. The prefix buffer can be a maximum of 155 characters and the name buffer can hold a maximum of 100 characters. If the path name cannot be split into these two parts by a slash, it cannot be archived. This limitation is due to the structure of tar archive headers, and must be maintained for compliance with standards and backwards compatibility.

Copying Files Using the -r and -w Flags

When both the -r and -w flags are specified, the pax command copies the files specified by the File parameters to the destination directory specified by the Directory parameter. If no files 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 flags can be specified with the -d, -i, -k, -l, -o, -p, -n, -s, -t, -u, -v, -X, and -y flags and with File parameters. The Directory parameter must be specified.

Copied files are the same as if they were written to an archive file and subsequently extracted, except that there may be hard links between the original and the copied files.

Modifying the Archive Algorithm Using the -o Flag

Use the -o flag to modify the archive algorithm according to keyword value pairs. The keyword value pairs must adhere to a correct archive format: the -x flag followed by cpio or ustar archive formats.

The -o flag currently supports the following keywords:

datastream=pathname,datastr_size=size

Variables

Directory	Specifies the path of a destination directory when copying files.
File	Specifies the path of a file to be copied or archived. If no file matches the File parameter, the pax command detects the error, exits, and writes a diagnostic message.
Pattern	Specifies a pattern that matches one or more paths of archive members. A \ (backslash) character is not recognized in the Pattern parameter and it prevents the subsequent character from having any special meaning. If no Pattern parameter is specified, all members are selected in the archive. If a Pattern parameter is specified, but no archive members are found that match the pattern specified, the pax command detects the error, exits, and writes a diagnostic message.

Flags

-a	Appends files to the end of an archive.

Note: Streaming Tape Devices do not allow append.

-b Blocking	Specifies the block size for output. The Blocking parameter specifies a positive decimal integer value that specifies the number of bytes per block. Devices and archive formats may impose restrictions on blocking. Blocking is automatically determined on input. Default blocking when creating archives depends on the archive format. (See the -x flag definition.) The value of the Blocking parameter may be one of the following: Integer b Specifies that the block size, in bytes, be the value of the positive decimal integer specified by the Integer parameter multiplied by 512. Integer k Specifies that the block size, in bytes, be the value of the positive decimal integer specified by the Integer parameter multiplied by 1024. Integer m Specifies that the block size, in bytes, be the value of the positive decimal integer specified by the Integer parameter multiplied by 1024 x 1024. Integer+Integer Specifies that the block size, in bytes, be the sum of the positive decimal integers specified by the Integer parameters.
-c	Matches all file or archive members except those specified by the Pattern parameter.
-d	Causes directories being copied, archived, or extracted, to match only the directory itself and not the contents of the directory.
-f Archive	Specifies the path of an archive file to be used instead of standard input (when the -w flag is not specified) or standard output (when the -w flag is specified but the -r flag is not). When specified with the -a flag option, any files written to the archive are appended to the end of the archive.
-i	Renames files or archives interactively. For each archive member that matches the Pattern parameter or file that matches a File parameter, a prompt is written to the display device that contains the name of a file or archive member. A line is then read from the display device. If this line is empty, the file or archive member is skipped. If this line consists of a single period, the file or archive member is processed with no modification to its name. Otherwise, its name is replaced with the contents of the line.
-k	Prevents the pax command from writing over existing files.
-l	Links files when copying files. Hard links are established between the source and destination file hierarchies whenever possible.
-n	Selects the first archive member that matches each Pattern parameter. No more than one archive member is matched for each pattern.
-o Options	Modifies the archiving algorithm according to the keyword value pairs specified as the Options parameter. The keyword value pairs must be in the following format: keyword[=value][,keyword[=value],]... Note: When specifying the keyword value, a / (backslash) must precede a literal comma to distinguish a single value from the next keyword value pair. The keyword of the value pairs must be in a correct archive format. You can specify the correct archive format by entering the -x flag followed by either the cpio or ustar archive formats. The -o flag supports the following keyword pair: datastream=pathname,datastr_size=size The datastream keyword indicates the incoming archive file is not in a file format; instead, it is a data stream from the standard input device. Consequently, the data should be archived as a regular file in a format recognized by the -x flag. The file name of the data stream should be specified in the pathname value and should include the identification of the person who invoked the command, the group identification, and the umask for the file mode. Note: The datastream keyword does not have a default variable size. You must specify one. The datastr_size keyword denotes the size of the data stream input in bytes in decimal digits. If the pax command reaches the end of file (EOF) character before it reads the size variable, it pads the archive file with null values. The null values make the archive file the same size as specified by the size parameter. If the data in the archive file exceeds the size specified, the pax command truncates the archive file to the size specified by the size variable. The pax command also stops taking input and closes the archive file. Note: You can specify multiple instances of keyword pairs. If you assign different values to the same keyword, the pax command uses the last value assigned to the keyword to execute the -o flag.
-p String	Specifies one or more file characteristics to be retained or discarded on extraction. The String parameter consists of the characters a, e, m, o, and p. Multiple characteristics can be concatenated within the same string and multiple -p flags can be specified. The specifications have the following meanings: a Does not retain file-access times. e Retains the user ID, group ID, file mode, access time, and modification time. m Does not retain file-modification times. o Retains the user ID and the group ID. p Retains the file modes. If neither the -e nor the -o flag is specified, or the user ID and group ID are not preserved for any reason, the pax command does not set the S_ISUID and S_ISGID bits of the file mode. 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 last flag specified takes precedence. For example, if `-p eme` is specified, file-modification times are retained.
-r	Reads an archive file from the standard input.
-s ReplacementString	Modifies file- or archive-member names specified by the Pattern or File parameters according to the substitution expression ReplacementString, using the syntax of the ed command. The substitution expression has the following format: -s /old/new/[gp] where (as in the ed command), old is a basic regular expression and new can contain an & (ampersand), \n (n is a digit) back references, or subexpression matching. The old string can also contain new-line characters. Any non-null character can be used as a delimiter (the / (backslash) is the delimiter in the example). Multiple -s flag 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 standard error. File or archive-member names that substitute to the empty string are ignored when reading and writing archives.
-t	Causes the access times of input files to be the same as they were before being read by the pax command.
-u	Ignores files that are older than a pre-existing file or archive member with the same name. When extracting files, 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, 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, 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 flags are specified, the -v flag produces a verbose table of contents; otherwise, archive member path names are written to standard error.
-w	Writes files 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 32768 in increments of 512 are supported. ustar Extended tar interchange format. The default blocking value for this format for character-special archive files is 10240. Blocking values from 512 to 32768 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 path name, the pax command does not descend into directories that have a different device ID.
-y	Prompts the user for the disposition of each file or archive member. For each member that matches the Pattern parameter or file that matches the File parameter, a prompt is displayed that contains the name of the file or archive member. If an affirmative response is entered, then the file is processed; otherwise, the file is ignored.

Flag Interaction and Processing Order

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

When extracting files, archive members are selected according to the user-specified pattern parameters as modified by the -c, -n, and -u flags. Then, any -s, -y, and -i flags modify, in that order, the names of the selected files. The -v flag writes the names resulting from these modifications.
When writing files to an archive file, or when copying files, the files are selected according to the user-specified path names as modified by the -n and -u flags. Then, any -s, -y, and -i flags modify, in that order, the names resulting from these modifications.
If both the -u and -n flags are specified, the pax command does not consider a file selected unless it is newer than the file to which it is compared.

Exit Status

This command returns the following exit values:

0	Successful completion.
>0	An error occurred.

Examples

To copy the olddir directory hierarchy to newdir, enter:
```
mkdir newdir
pax -rw olddir newdir
```
To copy the contents of the current directory to the tape drive, enter:
```
pax -w -f /dev/rmt0 
```
To archive the file xxx as XXX and display the successful substitution, enter:
```
pax -wvf/dev/rfd0 -s"/xxx/XXX/p" xxx
```
OR
```
pax -wvf/dev/rfd0 -s"/x/X/gp" xxx
```
To read a file from a standard input and dump it to a data stream file with a specified size, enter:
```
dd if=/dev/hd6 bs=36b count=480 | pax -wf /dev/rfd0 -o
datastream=_filename_,datastr_size=_size_
```

Files

/usr/bin/pax

Contains the pax command.

Related Information

The ed command, cpio command, tar command, and rmt command.

The Files Overview in AIX Version 4.3 System User's Guide: Operating System and Devices.