The pax(1) utility reads, writes, and lists the members
of an archive file (including tar(1)-format archives), and
also copies directory hierarchies. The pax(1) utility
operation is independent of the specific archive format and
supports a wide variety of different archive formats. A list of
supported archive formats can be found under the description of the
-x option.
If invoked as tar(1), pax(1) behaves as
tar(1). See the tar(1) reference page.
The presence of the -r and -w options specifies
the functional mode under which pax(1) will operate:
list, read, write, or copy
(none)
List. The pax(1) utility writes to standard output a
table of contents of the members of the archive file read from
standard input whose path names match the specified
patterns. The table of contents contains one file name per
line and is written using single-line buffering.
-r
Read. The pax(1) utility extracts the members of the
archive file read from the standard input, with path names matching
the specified patterns. The archive format and blocking is
automatically determined on input. When an extracted file is a
directory, the entire file hierarchy rooted at that directory is
extracted. All extracted files are created relative to the current
file hierarchy. The setting of ownership, access and modification
times, and file mode of the extracted files are discussed in more
detail under the -p option.
-w
Write. The pax(1) utility writes an archive containing
the file operands to standard output using the specified
archive format. When no file operands are specified, a list
of files to copy, with one per line, is read from standard input.
When a file operand is also a directory, the entire file
hierarchy rooted at that directory will be included.
-rw
Copy. The pax(1) utility copies the file operands
to the destination directory. When no file operands
are specified, a list of files to copy, with one per line, is read
from the standard input. When a file operand is also a
directory, the entire file hierarchy rooted at that directory will
be included. The effect of the copy operation is as if the
copied files were written to an archive file, and then subsequently
extracted, except that there might be hard links between the
original and the copied files (see the -l option later in
this topic).
The destination directory must not be one of the
file operands or a member of a file hierarchy rooted at one
of the file operands. The result of a copy operation
under these conditions is unpredictable.
When processing a damaged archive during a read or
list operation, pax(1) will attempt to recover from
media defects and will search through the archive to locate and
process the largest number of archive members possible (see the
-E option for more details on error handling).
The directory operand specifies a destination directory
path name. If the directory operand does not exist, is not
writable by the user, or is not of type directory, pax(1)
will exit with a non-zero exit status.
The pattern operand is used to select one or more path
names of archive members. Archive members are selected using the
pattern matching notation described by fnmatch(1). When the
pattern operand is not supplied, all members of the archive
will be selected. When a pattern matches a directory, the
entire file hierarchy rooted at that directory will be selected.
When a pattern operand does not select at least one archive
member, pax(1) will write these pattern operands in a
diagnostic message to standard error and then exit with a non-zero
exit status.
The file operand specifies the path name of a file to be
copied or archived. When a file operand does not select at
least one archive member, pax(1) will write these
file operand path names in a diagnostic message to standard
error, and then exit with a non-zero exit status.
Append files to the end of an archive that was
previously written. If an archive format is not specified with a
-x option, the format currently being used in the archive
will be selected. Any attempt to append to an archive in a format
different from the format already used in the archive will cause
pax(1) to exit immediately with a non-zero exit status. The
blocking size used in the archive volume where writing starts will
continue to be used for the remainder of that archive volume.
Caution
Many storage devices are not able to support the operations
necessary to perform an append operation. Any attempt to append to
an archive stored on such a device can damage the archive or have
other unpredictable results. An archive stored in a regular file
system file or on a disk device will usually support an append
operation.
-bblocksize
When writing an archive, block the output at a positive
decimal integer number of bytes per write to the archive file. The
blocksize must be a multiple of 512 bytes, with a maximum of
32256 bytes. A blocksize can end with k or b
to specify multiplication by 1024 (1 KB) or 512, respectively. A
pair of blocksizes can be separated by x to indicate
a product. A specific archive device can impose additional
restrictions on the size of blocking it will support. When blocking
is not specified, the default blocksize is dependent on the
specific archive format being used (see the -x option).
-Bbytes
Limit the number of bytes written to a single archive volume to
bytes. The bytes limit can end with m,
k, or b to specify multiplication by 1048576 (1 MB),
1024 (1 KB) or 512, respectively. A pair of bytes limits can
be separated by x to indicate a product.
Use this option only when writing an archive to a device that
supports an end-of-file read condition based on last (or largest)
write offset (such as a regular file or a tape drive). The use of
this option with a floppy or hard disk is not recommended.
-c
Match all file or archive members except those specified
by the pattern and file operands.
-d
Cause files of type directory being copied or archived, or
archive members of type directory being extracted, to match only
the directory file or archive member, and not the file hierarchy
rooted at the directory.
-D
This option is the same as the -u option, except that
the file status change time is checked instead of the file
modification time. The file status change time can be used to
select files whose file status information (such as, user
identifier (UID), group identifier (GID), and so on) is newer than
a copy of the file in the destination directory.
-farchive
Specify archive as the path name of the input or output
archive, overriding the default standard input (for list and
read or standard output (for write). A single archive
can span multiple files and different archive devices. When
required, pax(1) will prompt for the path name of the file
or device of the next volume in the archive. If this option is
used, it takes precedence over the value of the TAPE
environment variable.
-Elimit
Limit the number of consecutive read faults while trying to
read a flawed archives to limit. With a positive
limit, pax(1) will attempt to recover from an archive
read error and will continue processing, starting with the next
file stored in the archive. A limit of 0 will cause
pax(1) to stop operation after the first read error is
detected on an archive volume. A limit of NONE will
cause pax(1) to attempt to recover from read errors forever.
The default limit is a small positive number of retries.
Exercise extreme caution when using this option with NONE
as pax(1) can get stuck in an infinite loop on a very badly
flawed archive.
-Ggroup
Select a file based on its group name, or when starting
with a #, a numeric GID. A backslash (\) can be used
to escape the #. Multiple -G options can be supplied;
checking stops with the first match.
-i
Interactively rename files or archive members. For each archive
member matching a pattern operand or each file matching a
file operand, pax(1) will prompt to /dev/tty
giving the name of the file, its file mode, and its modification
time. The pax(1) utility will then read a line from
/dev/tty. If this line is blank, the file or archive member
is skipped. If this line consists of a single period, the file or
archive member is processed with no modification to its name.
Otherwise, its name is replaced with the contents of the line. The
pax(1) utility will immediately exit with a non-zero exit
status if <EOF> is encountered when reading a response, or if
/dev/tty cannot be opened for reading and writing.
-k
Do not overwrite existing files.
-l
Link files. (The letter ell). In the copy mode, hard
links are made between the source and destination file hierarchies
whenever possible.
-n
Select the first archive member that matches each
pattern operand. No more than one archive member is matched
for each pattern. When members of type directory are
matched, the file hierarchy rooted at that directory is also
matched (unless -d is also specified).
-ooptions
Information that is specific to the archive format specified by
-x, and which is used to modify the algorithm for extracting
or writing archive files. In general, options take the form:
name=value.
-pstring
Specify one or more file characteristic options (privileges).
The string option argument is a string that specifies the
file characteristics to be retained or discarded on extraction. The
string consists of the specification characters a, e,
m, o, and p. Multiple characteristics can be
concatenated within the same string, and multiple -p options
can be specified. The meaning of the specification characters are
as follows:
a
Do not preserve file access times. By default, file access
times are preserved whenever possible.
e
Preserve everything: the user identifier (UID), group
identifier (GID), file mode bits, file access time, and file
modification time. This is intended to be used by someone with the
appropriate privileges in order to preserve all aspects of the
files as they are recorded in the archive. The e flag is the
sum of the o and p flags.
m
Do not preserve file modification times. By default, file
modification times are preserved whenever possible.
o
Preserve the user identifier (UID) and group identifier
(GID).
p
Preserve the file mode bits. This intended to be used by a
user with regular privileges who wants to preserve all
aspects of the file other than the ownership.The file times are
preserved by default, but two other flags are offered to disable
this and use the time of extraction instead.
In the preceding list, "preserve" indicates that an attribute
stored in the archive is given to the extracted file, subject to
the permissions of the invoking process. Otherwise, the attribute
of the extracted file is determined as part of the normal file
creation action. If neither the e nor the o
specification character is specified, or the UID and GID are not
preserved for any reason, pax(1) will not set the
S_ISUID(setuid) and S_ISGID(setgid) bits of the file mode. If the preservation of any
of these items fails for any reason, pax(1) will write a
diagnostic message to standard error. Failure to preserve these
items will affect the final exit status, but will not cause the
extracted file to be deleted. If the file characteristic letters in
any of the string option arguments are duplicated or conflict with
each other, the one(s) given last will take precedence. For
example, if
-p eme
is specified, file modification times are still preserved.
-q
Suppress the error message indicating that not all Windows
permissions for a file were preserved in the archive.
-r
Read an archive file from standard input and extract the
specified files. If any intermediate directories are needed
in order to extract an archive member, these directories will be
created as if mkdir(1) was called with the bitwise inclusive
OR of S_IRWXU, S_IRWXG, and S_IRWXO as the mode argument. When the
selected archive format supports the specification of linked files,
and these files cannot be linked while the archive is being
extracted, pax(1) will write a diagnostic message to
standard error and exit with a non-zero exit status at the
completion of operation.
-sreplstr
Modify the file or archive member names specified by the
pattern or file operands according to the
substitution expression replstr, using the syntax of the
ed(1) utility regular expressions. The format of these
regular expressions is:
/old/new/[gp]
As in ed(1), old is a basic regular expression, and
new can contain an ampersand (&),
\n (where n is a digit), back references, or
subexpression matching. The old string can also contain
newline characters. Any non-null character can be used as a
delimiter (/ is shown here). Multiple -s expressions
can be specified. The expressions are applied in the order in which
they are specified on the command line, terminating with the first
successful substitution. The optional trailing g continues
to apply the substitution expression to the path name substring
that starts with the first character following the end of the last
successful substitution. The first unsuccessful substitution stops
the operation of the g option. The optional trailing
p will cause the final result of a successful substitution
to be written to standard error in the following format:
<original pathname> >> <new pathname>
File or archive member names that substitute to the empty string
are not selected and will be skipped.
-t
Reset the access times of any files or directories read or
accessed by pax(1) to be the same as they were before being
read or accessed by pax(1).
-T
[from_date][,to_date][/[c][m]]
Allow files to be selected based on a file-modification or
status-change time falling within a specified time range of
from_date to to_date (the dates are inclusive). If
only a from_date is supplied, all files with a modification
or status change time equal to or younger are selected. If only a
to_date is supplied, all files with a modification or status
change time equal to or older will be selected. When the
from_date is equal to the to_date, only files with a
modification or status change time of exactly that time will be
selected.
When pax(1) is in the write or copy mode,
the optional trailing field [c][m] can be used to
determine which file time (file status change, file modification or
both) are used in the comparison. If neither is specified, the
default is to use file modification time only. The m
specifies the comparison of file modification time (the time when
the file was last written). The c specifies the comparison
of status change time (the time when the file status information
was last changed, such as when it underwent a change of owner,
group, mode, and so on). When both c and m are
specified, the modification and status change times are both
compared. The status change time comparison is useful for selecting
files whose attributes were recently changed, or selecting files
that were recently created and had their modification time reset to
an older time (such as when a file is extracted from an archive and
the modification time is preserved). Time comparisons using both
file times is useful when pax(1) is used to create a
time-based incremental archive (only files that were changed during
a specified time range will be archived).
A time range is made up of six different fields, and each field
must contain two digits. The format is:
[yy[mm[dd[hh]]]]mm[.ss]
Where yy is the last two digits of the year, the first
mm is the month (from 01 to 12), dd is the day of the
month (from 01 to 31), hh is the hour of the day (from 00 to
23), the second mm is the minute (from 00 to 59), and
ss is the seconds (from 00 to 59). The minute field
mm is required; the other fields are optional and must be
added in the following order: hh, dd, mm,
yy. The ss field can be added independently of the
other fields. Time ranges are relative to the current time, so
-T 1234/cm
would select all files with a modification or status change time of
12:34 PM today or later. Multiple -T time range can be
supplied and checking stops with the first match.
-u
Ignore files that are older (having a less recent file
modification time) than a preexisting file or archive member with
the same name. During a read operation, an archive member with the
same name as a file in the file system will be extracted if the
archive member is newer than the file. During write operation, a
file system member with the same name as an archive member will be
written to the archive if it is newer than the archive member.
During a copy operation, the file in the destination hierarchy is
replaced by the file in the source hierarchy or by a link to the
file in the source hierarchy if the file in the source hierarchy is
newer.
-Uuser
Select a file based on its user name. To use a numeric
user identifier (UID) to identify the user, specify
#UID instead of user. To use # as a
character in user, specify \#. You can supply multiple
-U options; checking stops with the first match.
-v
During a list operation, produce a verbose table of
contents using the format of the ls(1) utility with the
-l option. For path names representing a hard link to a
previous member of the archive, the output has the format:
<ls -l listing> == <link name>
Where is the output format specified by the ls(1) utility
when used with the -l option. Otherwise, for all the other
operational modes (read, write, and copy) path names are written
and flushed to standard error without a trailing newline as soon as
processing begins on that file or archive member. The trailing
newline is not buffered, and is written only after the file has
been read or written.
-w
Write files to the standard output in the specified archive
format. When no file operands are specified, standard input
is read for a list of path names, with one per line without any
leading or trailing <blanks>.
-xformat
Specify the output archive format, with the default format
being ustar. The pax(1) utility currently supports
the following formats:
cpio
The extended cpio interchange format specified in the POSIX.2
standard. The default blocksize for this format is 5120 bytes.
Inode and device information about a file (used for detecting file
hard links by this format), which can be truncated by this format,
is detected by pax(1) and repaired.
bcpio
The old binary cpio format. The default blocksize for this
format is 5120 bytes. This format is not very portable and should
not be used when other formats are available. Inode and device
information about a file (used for detecting file hard links by
this format), which can be truncated by this format, is detected by
pax(1) and repaired.
sv4cpio
The System V release 4 cpio. The default blocksize for this
format is 5120 bytes. Inode and device information about a file
(used for detecting file hard links by this format), which can be
truncated by this format, is detected by pax(1) and
repaired.
sv4crc
The System V release 4 cpio with file cyclic redundancy check
(crc) checksums. The default blocksize for this format is 5120
bytes. Inode and device information about a file (used for
detecting file hard links by this format), which can be truncated
by this format, is detected by pax(1) and repaired.
tar
The old Berkeley Software Distribution (BSD) tar format
as found in BSD4.3. The default blocksize for this format is 10240
bytes. Path names stored by this format must be 100 characters or
fewer in length. Only regular files, hard links, and directories
will be archived (other file system types are not supported). For
backwards compatibility with even older tar formats, a
-o option can be used when writing an archive to omit the
storage of directories. This option takes the form:
-o write_opt=nodir
ustar
The extended tar interchange format specified in the
POSIX.2 standard. The default blocksize for this format is 10240
bytes. Path names stored by this format must be 250 characters or
fewer in length.
The pax(1) utility will detect and report any file that
it is unable to store or extract as the result of any specific
archive format restrictions. The individual archive formats can
impose additional restrictions on use. Typical archive format
restrictions include (but are not limited to): file path name
length, file size, link path name length and the type of the
file.
-X
When traversing the file hierarchy specified by a path name, do
not descend into directories that have a different device ID. See
the st_dev field as described in stat(1) for more
information about device identifiers.
-Y
This option is the same as the -D option, except that
the file status change time is checked using the path name created
after all the file name modifications have been completed.
-Z
This option is the same as the -u option, except that
the modification time is checked using the path name created after
all the file name modifications have been completed.
The options that operate on the names of files or archive
members (-c, -D, -G, -i, -n,
-s, -T, -u, -U, -v, -Y,
and -Z) interact as follows:
When extracting files during a read operation, archive members
are selected, based only on the user specified pattern operands as
modified by the -c, -D, -G, -n,
-T, -u, and -U options. Then, any -s
and -i options will modify, in that order, the names of
these selected files. The -Y and -Z options will then
be applied based on the final path name. Finally, the -v
option will write the names resulting from these modifications.
When archiving files during a write operation, or copying files
during a copy operation, archive members are selected according to
the user-specified path names as modified by the -D,
-G, -n, -T, -u, and -U options
(the -D option only applies during a copy operation). Then,
any -s and -i options will modify, in that order, the
names of these selected files. Then, during a copy operation the
-Y and the -Z options will be applied based on the
final path name. Finally, the -v option will write the names
resulting from these modifications.
When one or both of the -u or -D options are
specified along with the -n option, a file is not considered
selected unless it is newer than the file to which it is
compared.
gives the verbose table of contents for an archive stored in
filename.
The following commands:
mkdir newdir
cd olddir
pax -rw . newdir
will copy the entire olddir directory hierarchy to
newdir.
The command:
pax -r -s ',^//*usr//*,,' -f a.pax
reads the archive a.pax, with all files rooted in
/usr into the archive extracted relative to the current
directory.
The command:
pax -rw -i . dest_dir
can be used to interactively select the files to copy from the
current directory to dest_dir.
The command:
pax -r -pe -U andren -G bin -f a.pax
will extract all files from the archive a.pax that are owned
by andren with group bin, and will preserve all file permissions.
The command:
pax -r -w -v -Y -Z home /backup
will update (and list) only those files in the destination
directory /backup that are older (less recent file status
change or file modification times) than files with the same name
found in the source-file tree home.
The pax(1) utility will exit with one of the following
values:
0
All files were processed successfully.
1
An error occurred.
If pax(1) 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 will
continue. When pax cannot create a link to a file, it will
not 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(1) might have only
partially extracted a file that the user wanted. Additionally, the
file modes of extracted files and directories might contain
incorrect file bits, and the modification and access times might be
wrong.
If the creation of an archive is prematurely terminated by a
signal or error, pax(1) might have only partially created
the archive, which might violate the specific archive format
specification.
While doing a copy operation, if pax(1) detects a file
that is about to overwrite itself, the file is not copied, a
diagnostic message is written to standard error, and when
pax(1) completes it, will exit with a non-zero exit
status.
If a file has Windows-specific permissions in the discretionary
access control list (DACL) that are not mapped to UNIX permissions,
pax displays the following error message:
pax: warning: filename has additional permissions not
preserved in archive.
This indicates that these Windows permissions could not be
preserved in the archive.
Sometimes when creating or writing to an archive in tar,
ustar, bcpio, or cpio format, the following
message is printed to standard error:
uid nnnnnnn too large to fit in header: substituting 32666
On traditional systems, the UID and GID numbers fit into 16
bits, but on Interix, they can be 32 bits long. The Interix UIDs
and GIDs do not fit into the archive formats. This implementation
of pax(1) substitutes the value 32666 (decimal) for the
original UID or GID.
Substitution is not a problem with the ustar format. That
format records both the numeric and character string
representations of these numbers, and the string representation
takes precedence over the numeric.
The sv4cpio and sv4crc formats provide 32 bits for
UID and GID numbers, so no substitution is done.