STANDARD INPUT

If the −w option is specified, the standard input shall be used only if no file operands are specified. It shall be a text file containing a list of pathnames, one per line, without leading or trailing <blank>s. If neither the −f nor −w options are specified, the standard input shall be an archive file. (See INPUT FILES .) Otherwise, the standard input shall not be used.

INPUT FILES

The input file named by the archive option-argument, or standard input when the archive is read from there, shall be a file formatted according to one of the specifications in POSIX. 1 {8} 10.1, or some other, implementation-defined, format. The file /dev/tty shall be used to write prompts and read responses.

ENVIRONMENT VARIABLES

The following environment variables shall affect the execution of pax:

LANG

This variable shall determine the locale to use for the locale categories when both LC_ALL and the corresponding environment variable (beginning with LC_ ) do not specify a locale. See 2.6.

LC_ALL

This variable shall determine the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_.

LC_COLLATE

This variable shall determine the locale for the behavior of ranges, equivalence classes, and multicharacter collating elements used in the pattern matching expressions for the pattern operand, the basic regular expression for the −s option, and the extended regular expression defined for the yesexpr locale keyword in the LC_MESSAGES category.

LC_CTYPE

This variable shall determine the locale for the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters in arguments and input files) and the behavior of character classes within regular expressions and pattern matching.

LC_MESSAGES

This variable shall determine the processing of affirmative responses and the language in which messages should be written.

LC_TIME

This variable shall determine the format and contents of date and time strings when the −v option is specified.

ASYNCHRONOUS EVENTS

Default.

STANDARD OUTPUT

If the −w option is specified and neither the −f nor −r options are specified, the standard output shall be the archive formatted according to one of the specifications in POSIX. 1 {8} 10.1, or some other implementation-defined format. (See −x format under OPTIONS .) If neither the −r option nor the −w option is specified, the table of contents of the selected archive members shall be written to standard output using the following format:

"%s\n", <pathname> If neither the −r option nor the −w option is specified, but the −v option is specified, the table of contents of the selected archive members shall be written to standard output using the following formats: For pathnames representing hard links to previous members of the archive: "%s∆==∆%s\n", <ls −l listing>, <linkname> For all other pathnames: "%s\n", <ls −l listing> where <ls −l listing> shall be the format specified by the ls utility (see ls(1) ) with the −l option. When writing pathnames in this format, it is unspecified what is written for fields for which the underlying archive format does not have the correct information, although the correct number of <blank>-separated fields shall be written. When writing a table of contents of selected archive members, standard output shall not be buffered more than a line at a time.

STANDARD ERROR

If either or both of the −r option and the −w option are specified as well as the −v option, pax shall write the pathnames it processes to the standard error output using the following format:

"%s\n", <pathname> These pathnames shall be written as soon as processing is begun on the file or archive member, and shall be flushed to standard error. The trailing <newline>, which shall not be buffered, shall be written when the file has been read or written. If the −s option is specified, and the replacement string has a trailing p, substitutions shall be written to standard error in the following format: "%s∆>>∆%s\n", <original pathname>, <new pathname>

In all operating modes of pax (see DESCRIPTION ), 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 may be written to standard error. In all formats, for both standard output and standard error, it is unspecified how nonprintable characters in pathnames or linknames are written.

OUTPUT FILES

If the −r option is specified, the extracted or copied output files shall be of the archived file type. If the −w option is specified, but the −r option is not, the output file named by the −f option argument shall be a file formatted according to one of the specifications in POSIX. 1 {8} 10.1, or some other, implementation-defined, format.

EXAMPLES

The following command: pax -w -f /dev/rmt/1m . copies the contents of the current directory to tape drive 1, medium density (assuming historical System V device naming procedures. The historical BSD device name would be /dev/rmt9). The following commands: mkdir newdir pax -rw olddir newdir copy the olddir directory hierarchy to newdir. 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. The −p (privileges) option was invented to reconcile differences between historical tar and cpio implementations. In particular, the two utilities used −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 may seem complex, there are really two modes that will be most commonly used:

-p e ‘‘Preserve everything.’’ This would be used by the historical superuser, someone with all the appropriate privileges, to preserve all aspects of the files as they are recorded in the archive. The e flag is the sum of o and p, and other implementation-defined attributes.

-p p ‘‘Preserve’’ the file mode bits. This would be used by the user with regular privileges who wished to preserve aspects of the file other than the ownership. The file times are preserved by default, but two other flags are offered to disable these and use the time of extraction.

HISTORY OF DECISIONS MADE

The description of pax was adopted from a command written by Glenn Fowler of AT&T. It is a new utility, commissioned for this standard.

The table of contents output is written to standard output to facilitate pipeline processing. The output archive formats required are those defined in POSIX. 1 {8}; others, such as the historical tar format, may be added as an extension. The one pathname per line format of standard input precludes pathnames containing <newline>s. Although such pathnames violate the portable filename guidelines, they may exist and their presence may inhibit usage of pax within shell scripts. This problem is inherited from historical archive programs. The problem can be avoided by listing filename arguments on the command line instead of on standard input. An earlier draft had hard links displaying for all pathnames. This was removed because it complicates the output of the non −v case and does not match historical cpio usage. The hard-link information is available in the −v display.

The working group realizes that the presence of symbolic links will affect certain pax operations. Historical practice, in both System V and BSD -based systems, is that the physical traversal of the file hierarchy shall be the default, and an option is provided to cause the utility to do a logical traversal, that is, follow symbolic links. Historical practice has not been so consistent as to what option is used to cause the logical traversal; BSD systems have used −h (cp and tar) and −L (ls), while the SVID specifies −L (cpio and ls). Given this inconsistency, the −L option is recommended. The archive formats described in POSIX. 1 {8} have certain restrictions that have been brought along from historical usage. For example, there are restrictions on the length of pathnames stored in the archive. When pax is used in −rw mode, copying directory hierarchies, there is no stated dependency on these archive formats. Therefore, such restrictions should not apply. The POSIX. 2 working group is currently devising a new archive format to be published in a revision or amendment to this standard. It is expected that the ustar and cpio formats then will be retired from a future version of POSIX. 1 {8}. This new format will address all restrictions and new requirements for security labeling, etc. The pax utility should be upward-compatible enough to handle any such changes. The reason that the default −x format output format is implementation defined is to reserve the default format for this new standard interface. The −o option was devised to provide means of controlling the many aspects of international and security concerns without expending the entire alphabet of option letters for this, and possibly other, file formats. The −o string is meant to be specific for each −x format. Control of various file permissions and attributes that can be expressed in a binary way will continue to use the −p (permissions) option; the −o will be reserved for more involved requirements and will probably take a

pax -o name=value,name=value -o name=value

approach.

The fundamental difference in how cpio and tar viewed the world was in the way directories were treated. The cpio utility did not treat directories differently from other files, and to select a directory and its contents required that each file

in the hierarchy be explicitly specified. For tar, a directory matched every file in the file hierarchy it rooted. The pax utility offers both interfaces; by default, directories map into the file hierarchy they root. The −d option causes pax to skip any file not explicitly referenced, as cpio traditionally did. The tar-style behavior was chosen as the default because it was believed that this was the more common usage, and because tar is the more commonly available interface, as it was historically provided on both System V and BSD implementations. Because a file may be matched more than once without causing it to be selected multiple times, the traditional usage of piping an ls or find to the archive command works as always. The Data Interchange Format specification of POSIX. 1 {8} requires that processes with ‘‘appropriate privileges’’ shall always restore the ownership and permissions of extracted files exactly as archived. If viewed from the historic equivalence between super-user and ‘‘appropriate privileges,’’ there are two problems with this requirement. First, users running as super-users may unknowingly set dangerous permissions on extracted files. Second, it is needlessly limiting in that super-users cannot extract files and own them as super-user unless the archive was created by the super-user. (It should be noted that restoration of ownerships and permissions for the super-user, by default, is historical practice in cpio, but not in tar.) In order to avoid these two problems, the pax specification has an additional ‘‘privilege’’ mechanism, the −p option. Only a pax invocation with the POSIX. 1 {8} privileges needed, and which has the −p option set using the e specification character, has the ‘‘appropriate privilege’’ to restore full ownership and permission information. Note also that POSIX. 1 {8} 10.1 requires that the file ownership and access permissions shall be set, on extraction, in the same fashion as the POSIX. 1 {8} creat() function when provided the mode stored in the archive. This means that the file creation mask of the user is applied to the file permissions. The default blocksize value of 5120 for cpio was selected because it is one of the standard block-size values for cpio, set when the −B option is specified. (The other default block-size value for cpio is 512, and this was felt to be too small.) The default block value of 10 240 for tar was selected as that is the standard block-size value for BSD tar. The maximum block size of 32 256 (215−512) is the largest multiple of 512 that fits into a signed 16-bit tape controller transfer register. There are known limitations in some historic system that would prevent larger blocks from being accepted. Historic values were chosen to make compatibility with existing scripts using dd or similar utilities to manipulate archives more likely. Also, default block sizes for any file type other than character special has been deleted from the standard as unimportant and not likely to affect the structure of the resulting archive. Implementations are permitted to modify the block-size value based on the archive format or the device to which the archive is being written. This is to provide implementations the opportunity to take advantage of special types of devices, and should not be used without a great deal of consideration as it will almost certainly decrease archive portability.

The −n option in early drafts had three effects; the first was to cause special characters in patterns to not be treated specially. The second was to cause only the first file that matched a pattern to be extracted. The third was to cause pax to write a diagnostic message to standard error when no file was found matching a specified pattern. Only the second behavior is retained by POSIX. 2, for many reasons. First, it is in general a bad idea for a single option to have multiple effects. Second, the ability to make pattern matching characters act as normal characters is useful for other parts of pax than just file extraction. Third, a finer degree of control over the special characters is useful, because users may wish to normalize only a single special character in a single file name. Fourth, given a more general escape mechanism, the previous behavior of the −n option can be easily obtained using the −s option or a sed script. Finally, writing a diagnostic message when a pattern specified by the user is unmatched by any file is useful behavior in all cases. There are two methods of copying subtrees in POSIX. 2. The other method is described as part of the cp utility (see cp(1) ). Both methods are historical practice: cp provides a simpler, more intuitive interface, while pax offers a finer granularity of control. Each provides additional functionality to the other; in particular, pax maintains the hard-link structure of the hierarchy, while cp does not. It is the intention of the working group that the results be similar (using appropriate option combinations in both utilities). The results are not required to be identical; there seemed insufficient gain to applications to balance the difficulty of implementations having to guarantee that the results would be exactly identical. A single archive may span more than one file. See POSIX. 1 {8} 10.1.3. While POSIX. 1 {8} only refers to reading the archive file, it is reasonable that the format utility may also determine, in an implementation-defined manner, the next file to write. It is suggested that implementations provide informative messages to the user on the standard error whenever the archive file is changed. The −d option (do not create intermediate directories not listed in the archive) found in previous drafts of this standard was originally provided as a complement to the historic −d option of cpio. It has been deleted. The −s option in earlier drafts specified a subset of the substitution command from the ed utility. As there was no reason for only a subset to be supported, the −s option is now compatible with the current ed specification. Since the delimiter can be any nonnull character, the following usage with single spaces is valid: pax -s " foo bar " . . . The −t option (specify an implementation-defined identifier naming an input or output device) found in earlier drafts has been deleted because it is not historical practice and of limited utility. In particular, historic versions of neither cpio nor tar had the concept of devices that were not mapped into the file system; if the devices are mapped into the file system, the −f option is sufficient. The −o and −p options found in previous versions of this standard have been renamed to be −p and −t, respectively, to correspond more closely with the historic tar and cp utilities.

The default behavior of pax with regard to file modification times is the same as historical implementations of tar. It is not the historical behavior of cpio. Because the −i option uses /dev/tty, utilities without a controlling terminal will not be able to use this option. The −y option, found in earlier drafts, has been deleted because a line containing a single period for the −i option has equivalent functionality. The special lines for the −i option (a single period and the empty line) are historical practice in cpio. In earlier drafts, an −e charmap option was included to increase portability of files between systems using different coded character sets. This option was omitted because it was apparent that consensus could not be formed for it. It was an interface without implementation experience and overloaded the charmap file concept to provide additional uses its original authors had not intended. The developers of POSIX. 2 will consider other mechanisms for transporting files with nonportable names as they develop the new interchange format, described earlier.

The −k option was added to address international concerns about the dangers involved in the character set transformations of −e (if the target character set were different than the source, the file names might be transformed into names matching existing files) and was made more general to also protect files transferred between file systems with different NAME_MAX values (truncating a filename on a smaller system might also inadvertently overwrite existing files). As stated, it prevents any overwriting, even if the target file is older than the source, which is seen as a generally useful feature anyway. It is almost certain that appropriate privileges will be required for pax to accomplish parts of this specification. 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) will all probably require appropriate privileges. Some of the file characteristics referenced in this specification may not be supported by some archive formats. For example, neither the tar nor cpio formats contain the file access time. For this reason, the e specification character has been provided, intended to cause all file characteristics specified in the archive to be retained. It is required that extracted directories, by default, have their access and modification times and permissions set to the values specified in the archive. This has obvious problems in that the directories are almost certainly modified after being extracted and that directory permissions may not permit file creation. One possible solution is to create directories with the mode specified in the archive, as modified by the umask of the user, plus sufficient permissions to allow file creation. After all files have been extracted, pax would then reset the access and modification times and permissions as necessary. When the −r option is specified, and the −w option is not, implementations are permitted to overwrite files when the archive has multiple members with the same name. This may fail, of course, if permissions on the first version of the file

do not permit it to be overwritten.