SYNOPSIS
pax
[
pax
pax
pax
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 10/2016/2019/11/2022/2025 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
pax can read input archives and write output in
cpio and tar formats; see the
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
- 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.
-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 2016/2019/2022/2025 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 10/2016/2019/11/2022/2025 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
pathname == linkname
indicating that linkname is a hard link for pathname.
Handling Additional Attributes
With the
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
- 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
- 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
For information on how DACLs are restored, see Restoring DACLs.
When in list mode (neither
You can use
Enhanced or hybrid archives to which files have been appended may include
multiple copies of regular or special files. The behavior of
pax
- 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
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
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 10/2016/2019/11/2022/2025 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 10/2016/2019/11/2022/2025 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:
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 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022. Windows Server 2025.
The
The
On 10/2016/2019/11/2022/2025, 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 (
The
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
- Miscellaneous:
- iconv
MKS Toolkit Backup and Tape Handling Solutions Guide
PTC MKS Toolkit 10.5 Documentation Build 40.