pax

archiver for data interchange and file backup 

Command


SYNOPSIS

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

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

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

pax -r -w [-diklLNqUuvX] [-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.

The MKS version of pax can also save and restore additional 8.1/2012R2/10/2016/2019/11/2022 attributes.

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.

When pax adds a sparse file to an archive, it stores it as a non-sparse file but also stores the sparse attribute. When a file with a sparse attribute is extracted on a NTFS file system (which supports sparse files), the file is extracted as a sparse file. On other file systems, a warning is given and it is extracted as a non-sparse file. Sparse archive files are never created because most tapes, floppy disks, and other archiving media cannot understand them. It is recommended that you compress any archive which contain files with the sparse attribute set to keep the size of the archive reasonable.

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.

Note:

When you specify a compression option (-j or or -z) and neither -r nor -w and the specified archive is not compressed, an error message results and no table of contents is displayed.

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

Note:

When you specify a compression option (-j or or -z) with the -r option and the specified archive is not compressed, an error message results and no files are extracted.

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

-j 

uses the bzip2 format to compress the archive being created. When you extract from a an archive compressed using this format, pax automatically detects the bzip2 format and decompresses it appropriately.

Note:

Some versions of the pax utility on other systems may not automatically detect and decompress bzip2-compressed archives. To extract files from these archives on such a system, you should first decompress the archive using the bunzip2 utility.

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

Note:

Symbolic links are only available on 8.1/2012R2/2016/2019/2022 systems with the NTFS file system.

-l 

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

-N 

handles additional 8.1/2012R2/10/2016/2019/11/2022 attributes for each file in the archive. For each file in the archive, these additional attributes are stored in a file .filename_MKS_ACL.ksh (note the leading dot). This option has no effect when the TK_NTSECURITYINFO_OFF environment variable is set, because this environment variable disables the use of access control lists.

For full details on the behavior of -N and the handling of the additional attributes, see Handling Additional Attributes.

-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, pax supports options of the form keyword=value when the POSIX pax format is being used. The keyword can be any of the following pax extended header keywords:

atime
charset
comment
gname
linkpath
mtime
path
size
uname

See the pax file format reference page for more details on these keywords.

-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 Windows systems, pax adds a carriage return character (\r) before each newline (\n).

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.

In all modes, pax checks for the existence of a newer after making all substitutions specified with -s.

-u 

is identical to -U except that pax checks for the existence of a newer before making any substitutions specified with -s.

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

pax 

standing for the POSIX pax format, described on the pax reference page.

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.

Handling Additional Attributes

With the -N option, pax can handle saving and restoring additional 8.1/2012R2/10/2016/2019/11/2022 attributes. This option has no effect when the TK_NTSECURITYINFO_OFF environment variable is set.

The additional information for each file in the archive is stored in a file named .filename_MKS_ACL.ksh where filename is the name of the original file. This file (called a special file) is used to restore the additional attributes when the original file (called a regular file) is extracted. Archives containing special files are called enhanced archives.

When using -N with -w to create a new archive, for each file being added to the archive, pax also adds the corresponding special file. The has the same modification timestamp as the regular file and contains the chacl commands to restore the regular file's discretionary access control list (DACL), chown commands to set the owner and group information, and a chmod command to set the compressed attribute if the regular file has that attribute set.

Note:

Special files are created as temporary files and then added to the archive with the appropriate name. As a result, if a special file already exists when -N and -w are specified, that special file is ignored.

You can use -N with -r to extract files from an enhanced archive. For each regular file retrieved from the archive, the corresponding special file is also retrieved from the archive; the commands in this special file are then applied to the regular file and the special file is deleted (from the disk, but not from the archive).

Note:

To properly restore the ownership and group information for files being extracted from an enhanced archive, you must have the appropriate permissions as outlined in the chown reference page.

When you use -r without -N on an enhanced archive, pax extracts all files (both regular and special). Users with versions of MKS Toolkit that do not contain the -N feature of pax but do contain the chacl command can still make use of the special files in an enhanced archive. Such users can extract all the files in the archive with -r, and then use the find command to first execute the special files to restore the DACLs for the regular files and then delete those special files.

For information on how DACLs are restored, see Restoring DACLs.

When in list mode (neither -r nor -w is specified), -N displays only the regular files in the archive, unless you also specify -v. pax -vN displays both regular and special files as does pax in list mode without -N.

You can use -N with -wa to append regular and special files to an existing archive. If the existing archive is not an enhanced archive (that is, not created with the -N option of pax, cpio, or tar), the resulting archive is a hybrid, where only some files in the archive have 8.1/2012R2/10/2016/2019/11/2022 attributes associated with them. Similarly, by using pax -wa, you can append regular files without a corresponding special file to an existing enhanced archive.

Enhanced or hybrid archives to which files have been appended may include multiple copies of regular or special files. The behavior of pax -rN is undefined in this context; files may be inconsistent in the same way that is possible when multiple copies are included without the -N option. Appending files to an existing archive is not recommended when the append operation could result in multiple copies of a file in an archive.

Note:

If pax is interrupted while restoring an enhanced archive using -N, special files (that is, files of the form .filename_MKS_ACL.ksh may be left behind. You can delete these files with no consequence.

Restoring DACLs

When enhanced archives are created using pax -wN, the discretionary access control lists (DACLs) associated with file is preserved and these DACLs are restored when the files and directories are restored.

However, the access controls may still be different on restoration than for the original file, if files are retrieved to a location with different inheritable access control entries (ACEs) than the original location. ACEs can either be assigned explicitly to a given file or can be inherited from a higher directory. Access to a file depends both on the ACEs associated directly with that file, and on the ACEs inherited from above.

Consider the following hierarchy, with ACEs assigned to files and directories. No two ACEs in this example apply to the same user.

dir1  (ACE1)					dir4 (ACE4)
  |
dir2  (ACE2)
  |
file3 (ACE3)

Let ACE1 and ACE2 be inherited. Now run pax wN in directory dir1, saving dir2 and file3. ACE2 is saved with dir2 and ACE3 with file3. Now restore this pax archive to dir4.

To guarantee that all users have exactly the same access to restored files, no matter where they were restored in a directory tree, would require that all inheritance in the destination tree be overridden and that all inheritances in the source directory tree be expanded. In this example, it would require that ACE1 be assigned to dir2, and that ACE4 be ignored.

But this does not preserve the inheritance structure cleanly; restored files do not have the same ACEs that the original files did. Even if these files were restored to their original location under dir1, dir2 would have different ACEs, since ACE1 would have been assigned to dir2, and ignored the version of ACE1 associated with dir1. While users would have the same access as in the original case, the inheritance structure would be changed; in particular, dropping ACE1 from dir1 would have no effect in the restored setting, while it obviously would have in the original setting (and this gets far sloppier in a real example, where dir1 may contain many files, all of which would need to be assigned ACE1).

Instead, pax simply saves ACE2 with dir2 and ACE3 with file3. If the files are restored to dir1 (or any directory with inheritable ACE1), access rules are identical for saved and restored files. However, if dir2 and file3 are instead restored to dir4, with inheritable ACE4, the access rules are different.

This is right, though, in that the attributes have been retained for the files that pax saved and restored. Consider an analogy, where files are saved from a read-only file system (for example, a write-protected floppy disk), and restored to a read-write file system, such as the main hard drive. Here it seems clear that each file should be restored with its original permissions (which may well allow writing) instead of with read-only permission, based on an attribute that was set higher in the directory structure. Similarly, let the permissions on dir2 and file3 be wide open. If a user did not have read access to dir1 but did to dir4, restoring the archive to dir4 would give this user access to these files.


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 

ENVIRONMENT VARIABLES

TK_ARCHIVE_CHARSET 

Contains the format to be used by cpio, tar, pax, vpax, zip, or unzip when reading and writing file names to an archive. The value must be one of ASCII_ANSI, ASCII_OEM, or UTF-8 (or their equivalents) as described in the File Character Formats section of the unicode reference page.

When this variable is unset or it is set to a value other than those listed earlier, the default OEM character set is used.

TK_ASPI_SUPPORT_OFF 

If set, MKS Toolkit utilities do not use ASPI support if it is present and do not display warning messages if it is not.

TK_CLEAR_ARCHIVE_BIT 

When set, all files that are written to archives are stored in the archive with the archive bit cleared.

TK_NTLINKS_OFF 

MKS Toolkit supports hard links under 8.1/2012R2/10/2016/2019/11/2022 on NTFS file systems. There is a slight loss of performance for this support. If you do not require hard link support, you should set and export the environment variable TK_NTLINKS_OFF to disable this support.

TK_NTSECURITYINFO_OFF 

MKS Toolkit supports 8.1/2012R2/10/2016/2019/11/2022 security information on NTFS file systems. There is a slight loss of performance for this support. If you do not require any security information, you should set and export the environment variable TK_NTSECURITYINFO_OFF to disable this feature.

TK_UNIX_FILESYSTEM 

When this variable is set, the Enhanced UNIX Compatibility Mode is on and the virtual file system is in use.

When the Enhanced UNIX Compatibility Mode is on, pax stores all path names in an archive as virtual file system path names. This ensures that when such files are extracted on a system that uses a single-rooted file system similar to virtual file system (such as UNIX or Linux), they are put in the correct location. If you don't want virtual file system path names stored in the archives you create, turn off the Enhanced UNIX Compatibility Mode by unsetting the TK_UNIX_FILESYSTEM environment variable. As long as this environment variable is either set when performing both backup and restore operations, or unset when performing both, using pax to backup and restore should work as expected.

For details on the Enhanced UNIX Compatibility Mode and the virtual file system, see the EUCM reference page.


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. Windows 8.1. Windows Server 2012 R2. Windows 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022.

The -N option and the related handling of additional 8.1/2012R2/10/2016/2019/11/2022 attributes are MKS extensions. However, the resulting pax archives are in standard format and can be read by standard implementations of pax, tar, or cpio (depending on the format used).

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

On 8.1/2012R2/10/2016/2019/11/2022, pax recognizes device names only if you apply the prefix //./ to every device reference, as follows:

//./TAPE0   instead of TAPE0

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

/dev/mt0

has the same effect as specifying //./TAPE0, with the added advantage that pax automatically senses and sets the correct block size of the tape.


WARNING

Before performing a raw disk input/output operation on a given disk, you must first read a properly formatted disk of the same size in the same drive. For example, if you want to use a 1.44MB disk in drive A: for raw disk input, you first perform a command like ls or dir on a different, properly formatted 1.44 MB disk in that drive. Once this is done, place the disk that you want to use for raw disk input/output in the appropriate drive and issue the PTC MKS Toolkit command that you want to use.


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 PTC MKS Toolkit sort utility (or one compatible with it) is the first one located by the command search path.


AVAILABILITY

PTC MKS Toolkit for System Administrators
PTC MKS Toolkit for Developers
PTC MKS Toolkit for Interoperability
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Commands:
cpio, ls, mkszip, mt, tar, uncompress, vpax

File Formats:
cpio, pax, tape, tar

Miscellaneous:
iconv

MKS Toolkit Backup and Tape Handling Solutions Guide


PTC MKS Toolkit 10.4 Documentation Build 39.