pax [-cdnv] [-H | -L] [-f archive] [-o options]... 
 [-s replstr]... [pattern]...

pax -r [-cdiknuv@/] [-H | -L] [-f archive] [-o options]... 
 [-p string]... [-s replstr]... [pattern]...

pax -w [-dituvX@/] [-H | -L] [-b blocksize] [-a] 
 [-f archive] [-o options]... [-s replstr]... 
 [-x format] [file]...

pax -r -w [-diklntuvX@/] [-H | -L] [-o options]... 
 [-p string]... [-s replstr]... [file]... directory

pax reads, writes, and writes lists of the members of archive files and copies directory hierarchies. A variety of archive formats are supported. See the -x format option.

The action to be taken depends on the presence of the -r and -w options. The four combinations of -r and -w are referred to as the four modes of operation: list, read, write, and copy modes, corresponding respectively to the four forms shown in the SYNOPSIS.

list

read

write

copy

In read or copy modes, if intermediate directories are necessary to extract an archive member, pax performs actions equivalent to the mkdir(2) function, called with the following arguments:

If any specified pattern or file operands are not matched by at least one file or archive member, pax writes a diagnostic message to standard error for each one that did not match and exits with a non-zero exit status.

The supported archive formats are automatically detected on input. The default output archive format is tar(1).

A single archive can span multiple files. pax determines what file to read or write as the next file.

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, except if the files to be linked are symbolic links and the system is not capable of making hard links to symbolic links. In that case, separate copies of the symbolic link are created instead. Any of the various names in the archive that represent a file can be used to select the file for extraction. For archive formats that do not store file contents with each name that causes a hard link, if the file that contains the data is not extracted during this pax session, either the data is restored from the original file, or a diagnostic message is displayed with the name of a file that can be used to extract the data. In traversing directories, pax detects infinite loops, that is, entering a previously visited directory that is an ancestor of the last file visited. When it detects an infinite loop, pax writes a diagnostic message to standard error and terminates.

The following options are supported:

-a

-b blocksize

-c

-d

-f archive

-H

-i

-k

-l

-L

-n

-o options

keyword[[:]=value][,keyword[[:]=value], ...]

-o delete=security.*

%d/PaxHeaders.%p/%f

$TMPDIR/GlobalHead.%p.%n

pax -r -o "
gname:=mygroup,
" <archive

-p string

-r

-s replstr

-s /old/new/ [gp]

-t

-u

-v

-w

-x format

-X

-@

-/

Specifying more than one of the mutually-exclusive options -H and -L is not considered an error. The last option specified determines the behavior of the utility.

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

In read mode, the archive members are selected based on the user-specified pattern operands as modified by the -c, -n and -u options. Then, any -s and -i options modify, in that order, the names of the selected files. The -v option writes names resulting from these modifications.

In write mode, the files are selected based on the user-specified path names as modified by the -n and -u options. Then, any -s and -i options modify, in that order, the names of these selected files. The -v option writes names resulting from these modifications.

If both the -u and -n options are specified, pax does not consider a file selected unless it is newer than the file to which it is compared.

In list mode with the -o listopt=format option, the format argument is applied for each selected file. pax appends a NEWLINE to the listopt output for each selected file. The format argument is used as the format string with the following exceptions. (See printf(1) for the first five exceptions.)

%b %e %H:%M %Y

(keyword[,keyword] ... )

"%s -> %s", value of keyword, contents of link

The following operands are supported:

directory

file

pattern

Output formats are discussed below:

In write mode, if -f is not specified, the standard output is the archive formatted according to one of the formats described below. See -x format for a list of supported formats.

In list mode, when the -o listopt=format option has been specified, the selected archive members are written to standard output using the format described above under List Mode Format Specifications. In list mode without the -o listopt=format option, the table of contents of the selected archive members are written to standard output using the following format:

"%s\en", pathname

If the -v option is specified in list mode, the table of contents of the selected archive members are written to standard output using the following formats:

"%s == %s\en", <ls -l listing, linkname

"%s\en", <ls -l listing>

In list mode, standard output is not buffered more than a line at a time.

If -v is specified in read, write or copy modes, pax writes the path names it processes to the standard error output using the following format:

"%s\en", pathname

These path names are written as soon as processing is begun on the file or archive member, and are flushed to standard error. The trailing NEWLINE character, which is not buffered, is written when the file has been read or written.

If the -s option is specified, and the replacement string has a trailing p, substitutions are written to standard error in the following format:

"%s >> %s\en", <original pathname>, <new pathname>

In all operating modes of pax, optional messages of unspecified format concerning the input archive format and volume number, the number of files, blocks, volumes, and media parts as well as other diagnostic messages can be written to standard error.

In all formats, for both standard output and standard error, it is unspecified how non-printable characters in path names or link names are written.

When pax is in read mode or list mode, using the -x pax archive format, and a file name, link name, owner name, or any other field in an extended header record cannot be translated from the pax UTF-8 codeset format to the codeset and current locale of the implementation, pax writes a diagnostic message to standard error, processes the file as described for the -o invalid=option, and then processes the next file in the archive.

In read mode, the extracted output files are of the archived file type. In copy mode, the copied output files are the type of the file being copied . In either mode, existing files in the destination hierarchy are overwritten only when all permission (-p), modification time (-u), and invalid-value (-o invalid=) tests allow it. In write mode, the output file named by the -f option-argument is a file formatted according to one of the specifications in IEEE Std 1003.1-2001.

If pax cannot create a file or a link when reading an archive, or cannot find a file when writing an archive, or cannot preserve the user ID, group ID, or file mode when the -p option is specified, a diagnostic message is written to standard error and a non-zero exit status is returned, but processing continues. In the case where pax cannot create a link to a file, pax does not, by default, create a second copy of the file.

If the extraction of a file from an archive is prematurely terminated by a signal or error, pax can have only partially extracted the file or, if the -n option was not specified, can have extracted a file of the same name as that specified by the user, but which is not the file the user wanted. Additionally, the file modes of extracted directories can have additional bits from the read, write, execute mask set as well as incorrect modification and access times.

The -p (privileges) option was invented to reconcile differences between historical tar(1) and cpio(1) implementations. In particular, the two utilities use -m in diametrically opposed ways. The -p option also provides a consistent means of extending the ways in which future file attributes can be addressed, such as for enhanced security systems or high-performance files. Although it can seem complex, there are really two modes that are most commonly used:

-p e

-p p

The one path name per line format of standard input precludes path names containing newlines. Although such path names violate the portable filename guidelines, they can exist and their presence can inhibit usage of pax within shell scripts. This problem is inherited from historical archive programs. The problem can be avoided by listing file name arguments on the command line instead of on standard input.

It is almost certain that appropriate privileges are required for pax to accomplish parts of this. Specifically, creating files of type block special or character special, restoring file access times unless the files are owned by the user (the -t option), or preserving file owner, group, and mode (the -p option) all probably require appropriate privileges.

In read mode, implementations are permitted to overwrite files when the archive has multiple members with the same name. This can fail if permissions on the first version of the file do not permit it to be overwritten.

When using the -x xustar and -x -pax archive formats, if the underlying file system reports that the file being archived contains holes, the Solaris pax utility records the presence of holes in an extended header record when the file is archived. If this extended header record is associated with a file in the archive, those holes are recreated whenever that file is extracted from the archive. See the SEEK_DATA and SEEK_HOLE whence values in lseek(2). In all other cases, any NUL (\e0) characters found in the archive is written to the file when it is extracted.

See largefile(5) for the description of the behavior of pax when encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).

In write mode, the standard input is used only if no file operands are specified. It is a text file containing a list of path names, one per line, without leading or trailing blanks. In list and read modes, if -f is not specified, the standard input is an archive file. Otherwise, the standard input is not used.

The input file named by the archive option-argument, or standard input when the archive is read from there, is a file formatted according to one of the formats described below. See Extended Description. The file /dev/tty is used to write prompts and read responses.

Example 1 Copying the Contents of the Current Directory

The following command:

example% pax -w -f /dev/rmt/1m .

copies the contents of the current directory to tape drive 1, medium density. This assumes historical System V device naming procedures. The historical BSD device name would be /dev/rmt9.

Example 2 Copying the Directory Hierarchy

The following commands:

example% mkdir newdir
example% pax -rw olddir newdir

copy the olddir directory hierarchy to newdir.

Example 3 Reading an Archive Extracted Relative to the Current Directory

The following command:

example% pax -r -s ',^//*usr//*,,' -f a.pax

reads the archive a.pax, with all files rooted in /usr in the archive extracted relative to the current directory.

Example 4 Overriding the Default Output Description

Using the option:

-o listopt="%M %(atime)T %(size)D %(name)s"

overrides the default output description in Standard Output and instead writes:

-rw-rw- - - Jan 12 15:53 2003 1492 /usr/foo/bar

Using the options:

-o listopt='%L\et%(size)D\en%.7' \e
-o listopt='(name)s\en%(atime)T\en%T'

overrides the default output description in standard output and instead writes:

usr/foo/bar -> /tmp 1492
/usr/foo
Jan 12 15:53 1991
Jan 31 15:53 2003

See environ(5) for descriptions of the following environment variables that affect the execution of pax: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, LC_TIME, and NLSPATH.

LC_COLLATE

TMPDIR

TZ

The following exit values are returned:

0

>0

A pax archive tape or file produced in the -xpax format contains a series of blocks. The physical layout of the archive is identical to the ustar format described in ustar Interchange Format. Each file archived is represented by the following sequence:

At the end of the archive file there are two 512-byte blocks filled with binary zeroes, interpreted as an end-of-archive indicator.

The following is a schematic of an example archive with global extended header records and two actual files in pax format archive. In the example, the second file in the archive has no extended header preceding it, presumably because it has no need for extended attributes.

The pax header block is identical to the ustar header block described in ustar Interchange Format except that two additional typeflag values are defined:

g

x

For both of these types, the size field is the size of the extended header records in octets. The other fields in the header block are not meaningful to this version of pax. However, if this archive is read by pax conforming to a previous version of ISO POSIX-2:1993 Standard, the header block fields are used to create a regular file that contains the extended header records as data. Therefore, header block field values should be selected to provide reasonable file access to this regular file.

A further difference from the ustar header block is that data blocks for files of typeflag 1 (the digit one) (hard link) might be included, which means that the size field can be greater than zero. Archives created by pax -o linkdata includes these data blocks with the hard links.

A pax extended header contains values that are inappropriate for the ustar header block because of limitations in that format: fields requiring a character encoding other than that described in the ISO/IEC 646: 1991 standard, fields representing file attributes not described in the ustar header, and fields whose format or length do not fit the requirements of the ustar header. The values in an extended header add attributes to the specified file or files or override values in the specified header blocks, as indicated in the following list of keywords. See the description of the typeflag g header block.

An extended header consists of one or more records, each constructed as follows:

"%d %s=%s\en", length, keyword, value

The extended header records are encoded according to the ISO/IEC 10646-1: 2000 standard (UTF-8). length, BLANK, equals sign (=), and NEWLINE are limited to the portable character set, as encoded in UTF-8. keyword and value can be any UTF-8 characters. length is the decimal length of the extended header record in octets, including the trailing NEWLINE.

keyword is one of the entries from the following list or a keyword provided as an implementation extension. Keywords consisting entirely of lowercase letters, digits, and periods are reserved for future standardization. A keyword does not include an equals sign.

In the following list, the notation of file(s) or block(s) are used to acknowledge that a keyword affects the specified single file after a typeflag x extended header, but possibly multiple files after typeflag g. Any requirements in the list for pax to include a record when in write or copy mode applies only when such a record has not already been provided through the use of the -o option. When used in copy mode, pax behaves as if an archive had been created with applicable extended header records and then extracted.

atime

charset

comment

gid

gname

linkpath

mtime

path

realtime.any

security.any

size

uid

uname

If the value field is zero length, it deletes any header block field, previously entered extended header value, or global extended header value of the same name.

If a keyword in an extended header record (or in an -o option-argument) overrides or deletes a corresponding field in the ustar header block, pax ignores the contents of that header block field.

Unlike the ustar header block fields, NULLs does not delimit values; all characters within the value field are considered data for the field.

This section describes the precedence in which the various header records and fields and command line options are selected to apply to a file in the archive. When pax is used in read or list modes, it determines a file attribute in the following sequence:

pax writes an mtime record for each file in write or copy modes if the file's modification time cannot be represented exactly in the ustar header logical record described in ustar Interchange Format. This can occur if the time is out of ustar range, or if the file system of the underlying implementation supports non-integer time granularities and the time is not an integer. All of these time records are formatted as a decimal representation of the time in seconds since the Epoch. If a period (.) decimal point character is present, the digits to the right of the point represents the units of a sub-second timing granularity, where the first digit is tenths of a second and each subsequent digit is a tenth of the previous digit. In read or copy mode, pax truncates the time of a file to the greatest value that is not greater than the input header file time. In write or copy mode, pax outputs a time exactly if it can be represented exactly as a decimal number, and otherwise generates only enough digits so that the same time is recovered if the file is extracted on a system whose underlying implementation supports the same time granularity.

A ustar archive tape or file contains a series of logical records. Each logical record is a fixed-size logical record of 512 octets. Although this format can be thought of as being stored on 9-track industry-standard 12.7mm (0.5 in) magnetic tape, other types of transportable media are not excluded. Each file archived is represented by a header logical record that describes the file, followed by zero or more logical records that give the contents of the file. At the end of the archive file there are two 512-octet logical records filled with binary zeros, interpreted as an end-of-archive indicator.

The logical records can be grouped for physical I/O operations, as described under the -bblocksize and -x ustar options. Each group of logical records can be written with a single operation equivalent to the write(2) function. On magnetic tape, the result of this write is a single tape physical block. The last physical block always is the full size, so logical records after the two zero logical records can contain undefined data.

The header logical record is structured as shown in the following table. All lengths and offsets are in decimal. Table 1 ustar Header Block

All characters in the header logical record is represented in the coded character set of the ISO/IEC 646: 1991 standard. For maximum portability between implementations, names should be selected from characters represented by the portable filename character set as octets with the most significant bit zero. If an implementation supports the use of characters outside of slash and the portable filename character set in names for files, users, and groups, one or more implementation-defined encodings of these characters are provided for interchange purposes.

pax never creates filenames on the local system that cannot be accessed using the procedures described in IEEE Std 1003.1-200x. If a filename is found on the medium that would create an invalid filename, it is implementation-defined whether the data from the file is stored on the file hierarchy and under what name it is stored. pax can choose to ignore these files as long as it produces an error indicating that the file is being ignored. Each field within the header logical record is contiguous; that is, there is no padding used.

Each field within the header logical record is contiguous. There is no padding used. Each character on the archive medium is stored contiguously.

The fields magic, uname and gname are character strings, each of which is terminated by a NULL character. The fields name, linkname, and prefix are NULL-terminated character strings except when all characters in the array contain non-NULL characters including the last character. The version field is two octets containing the characters 00 (zero-zero) The typeflag contains a single character. All other fields are leading zero-filled octal numbers using digits from the ISO/IEC 646:1991 standard IRV. Each numeric field is terminated by one or more SPACE of NULL characters.

Each character on the archive medium is stored contiguously. The fields magic, uname, and gname are character strings each terminated by a NULL character.

name, linkname, and prefix are NULL-terminated character strings except when all characters in the array contain non-NULL characters including the last character. The version field is two octets containing the characters 00 (zero-zero). The typeflag contains a single character. All other fields are leading zero-filled octal numbers using digits from the ISO/IEC 646: 1991 standard IRV. Each numeric field is terminated by one or more spaces or NULL characters.

The name and the prefix fields produce the pathname of the file. A new pathname is formed, if prefix is not an empty string (its first character is not NULL), by concatenating prefix (up to the first NULL character), a slash character, and name; otherwise, name is used alone. In either case, name is terminated at the first NULL character. If prefix begins with a NULL character, it is ignored. In this manner, pathnames of at most 256 characters can be supported. If a pathname does not fit in the space provided, pax notifies the user of the error, and does not store any part of the file-header or data-on the medium.

The linkname field does not use the prefix to produce a pathname. As such, a linkname is limited to 100 characters. If the name does not fit in the space provided, pax notifies the user of the error, and does not attempt to store the link on the medium. The mode field provides 12 bits encoded in the ISO/IEC 646: 1991 standard octal digit representation. The encoded bits represent the following values in the ustar mode field:

When appropriate privilege is required to set one of these mode bits, and the user restoring the files from the archive does not have the appropriate privilege, the mode bits for which the user does not have appropriate privilege are ignored. Some of the mode bits in the archive format are not mentioned elsewhere in volume IEEE Std 1003.1-200x. If the implementation does not support those bits, they can be ignored.

The uid and gid fields are the user and group ID of the owner and group of the file, respectively.

The size field is the size of the file in octets. If the typeflag field is set to specify a file to be of type 1 (a link) or 2 (a symbolic link), the size field is specified as zero. If the typeflag field is set to specify a file of type 5 (directory), the size field is interpreted as described under the definition of that record type. No data logical records are stored for types 1, 2, or 5. If the typeflag field is set to 3 (character special file), 4 (block special file), or 6 (FIFO), the meaning of the size field is unspecified by volume IEEE Std 1003.1-200x, and no data logical records is stored on the medium. Additionally, for type 6, the size field is ignored when reading. If the typeflag field is set to any other value, the number of logical records written following the header is (size+511)/512, ignoring any fraction in the result of the division.

The mtime field is the modification time of the file at the time it was archived. It is the ISO/IEC 646: 1991 standard representation of the octal value of the modification time obtained from the stat() function.

The chksum field is the ISO/IEC 646: 1991 standard IRV representation of the octal value of the simple sum of all octets in the header logical record. Each octet in the header is treated as an unsigned value. These values are added to an unsigned integer, initialized to zero, the precision of which is not less than 17 bits. When calculating the checksum, the chksum field is treated as if it were all spaces.

The typeflag field specifies the type of file archived. If a particular implementation does not recognize the type, or the user does not have appropriate privilege to create that type, the file is extracted as if it were a regular file if the file type is defined to have a meaning for the size field that could cause data logical records to be written on the medium. If conversion to a regular file occurs, pax produces an error indicating that the conversion took place. All of the typeflag fields are coded in the ISO/IEC 646: 1991 standard IRV:

0

1

2

3,4

5

6

7

A-Z

SUN.devmajor

SUN.devminor

SUN.holesdata

SPACEdata_offsetSPACEhole_offset

49 SUN.holesdata= 0 8192 24576 32768 49152 49159

X

E

Attempts to archive a socket using ustar interchange format produce a diagnostic message. Handling of other file types is implementation-defined.

The magic field is the specification that this archive was output in this archive format. If this field contains ustar (the five characters from the ISO/IEC 646: 1991 standard IRV shown followed by NULL), the uname and gname fields contain the ISO/IEC 646: 1991 standard IRV representation of the owner and group of the file, respectively (truncated to fit, if necessary). When the file is restored by a privileged, protection-preserving version of the utility, the user and group databases are scanned for these names. If found, the user and group IDs contained within these files are used rather than the values contained within the uid and gid fields.

The octet-oriented cpio archive format are a series of entries, each comprising a header that describes the file, name of the file, and contents of the file.

An archive can be recorded as a series of fixed-size blocks of octets. This blocking is be used only to make physical I/O more efficient. The last group of blocks are always at the full size.

For the octet-oriented cpio archive format, the individual entry information are in the order indicated and described by the following table: Octet-Oriented cpio Archive Entry. See the cpio.h header for additional details.

For each file in the archive, a header as defined previously written. The information in the header fields is written as streams of the ISO/IEC 646: 1991 standard characters interpreted as octal numbers. The octal numbers are extended to the necessary length by appending the ISO/IEC 646: 1991 standard IRV zeros at the most-significant-digit end of the number. The result is written to the most-significant digit of the stream of octets first. The fields are interpreted as follows:

c_magic

c_dev,c_ino

c_mode

c_uid

c_gid

c_nlink

c_rdev

c_mtime

c_namesize

c_filesize

The c_name field contains the pathname of the file. The length of this field in octets is the value of c_namesize. If a filename is found on the medium that would create an invalid pathname, it is implementation-defined whether the data from the file is stored on the file hierarchy and under what name it is stored. All characters are represented in the ISO/IEC 646: 1991 standard IRV. For maximum portability between implementations, names should be selected from characters represented by the portable filename character set as octets with the most significant bit zero. If an implementation supports the use of characters outside the portable filename character set in names for files, users, and groups, one or more implementation-defined encodings of these characters are provided for interchange purposes.pax does not create filenames on the local system that cannot be accessed by way of the procedures described in volume IEEE Std 1003.1-200x. If a filename is found on the medium that would create an invalid filename, it is implementation-defined whether the data from the file is stored on the local file system and under what name it is stored. pax can choose to ignore these files as long as it produces an error indicating that the file is being ignored.

Following c_name, there is c_filesize octets of data. Interpretation of such data occurs in a manner dependent on the file. If c_filesize is zero, no data is contained in c_filedata . When restoring from an archive:

FIFO special files, directories, and the trailer are recorded with c_filesize equal to zero. For other special files, c_filesize is unspecified in volume IEEE Std 1003.1-200x. The header for the next file entry in the archive are written directly after the last octet of the file entry preceding it. A header denoting the filename trailer indicates the end of the archive; the contents of octets in the last block of the archive following such a header are undefined.

See attributes(5) for descriptions of the following attributes:

chmod(1), cpio(1), ed(1), printf(1), tar(1), mkdir(2), lseek(2), stat(2), write(2), archives.h(3HEAD), attributes(5), environ(5), fnmatch(5), formats(5)fsattr(5), largefile(5), regex(5), standards(5)

IEEE Std 1003.1-200x, ISO/IEC 646: 1991, ISO POSIX-2:1993 Standard