The pax utility shall conform to the Base Definitions volume of
POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines, except
that the order of presentation of the -o, -p, and -s options is
significant.
The following options shall be supported:
-r Read an archive file from standard input.
-w Write files to the standard output in the specified
archive format.
-a Append files to the end of the archive. It is
implementation-defined which devices on the system
support appending. Additional file formats unspecified
by this volume of POSIX.1‐2017 may impose restrictions
on appending.
-b blocksize
Block the output at a positive decimal integer number
of bytes per write to the archive file. Devices and
archive formats may impose restrictions on blocking.
Blocking shall be automatically determined on input.
Conforming applications shall not specify a blocksize
value larger than 32256. Default blocking when creating
archives depends on the archive format. (See the -x
option below.)
-c Match all file or archive members except those
specified by the pattern or file operands.
-d Cause files of type directory being copied or archived
or archive members of type directory being extracted or
listed to match only the file or archive member itself
and not the file hierarchy rooted at the file.
-f archive
Specify the pathname of the input or output archive,
overriding the default standard input (in list or read
modes) or standard output (write mode).
-H If a symbolic link referencing a file of type directory
is specified on the command line, pax shall archive the
file hierarchy rooted in the file referenced by the
link, using the name of the link as the root of the
file hierarchy. Otherwise, if a symbolic link
referencing a file of any other file type which pax can
normally archive is specified on the command line, then
pax shall archive the file referenced by the link,
using the name of the link. The default behavior, when
neither -H or -L are specified, shall be to archive the
symbolic link itself.
-i Interactively rename files or archive members. For each
archive member matching a pattern operand or file
matching a file operand, a prompt shall be written to
the file /dev/tty. The prompt shall contain the name
of the file or archive member, but the format is
otherwise unspecified. A line shall then be read from
/dev/tty. If this line is blank, the file or archive
member shall be skipped. If this line consists of a
single period, the file or archive member shall be
processed with no modification to its name. Otherwise,
its name shall be replaced with the contents of the
line. The pax utility shall immediately exit with a
non-zero exit status if end-of-file is encountered when
reading a response or if /dev/tty cannot be opened for
reading and writing.
The results of extracting a hard link to a file that
has been renamed during extraction are unspecified.
-k Prevent the overwriting of existing files.
-l (The letter ell.) In copy mode, hard links shall be
made between the source and destination file
hierarchies whenever possible. If specified in
conjunction with -H or -L, when a symbolic link is
encountered, the hard link created in the destination
file hierarchy shall be to the file referenced by the
symbolic link. If specified when neither -H nor -L is
specified, when a symbolic link is encountered, the
implementation shall create a hard link to the symbolic
link in the source file hierarchy or copy the symbolic
link to the destination.
-L If a symbolic link referencing a file of type directory
is specified on the command line or encountered during
the traversal of a file hierarchy, pax shall archive
the file hierarchy rooted in the file referenced by the
link, using the name of the link as the root of the
file hierarchy. Otherwise, if a symbolic link
referencing a file of any other file type which pax can
normally archive is specified on the command line or
encountered during the traversal of a file hierarchy,
pax shall archive the file referenced by the link,
using the name of the link. The default behavior, when
neither -H or -L are specified, shall be to archive the
symbolic link itself.
-n Select the first archive member that matches each
pattern operand. No more than one archive member shall
be matched for each pattern (although members of type
directory shall still match the file hierarchy rooted
at that file).
-o options
Provide information to the implementation to modify the
algorithm for extracting or writing files. The value of
options shall consist of one or more <comma>-separated
keywords of the form:
keyword[[:]=value][,keyword[[:]=value], ...]
Some keywords apply only to certain file formats, as
indicated with each description. Use of keywords that
are inapplicable to the file format being processed
produces undefined results.
Keywords in the options argument shall be a string that
would be a valid portable filename as described in the
Base Definitions volume of POSIX.1‐2017, Section 3.282,
Portable Filename Character Set.
Note: Keywords are not expected to be filenames,
merely to follow the same character composition
rules as portable filenames.
Keywords can be preceded with white space. The value
field shall consist of zero or more characters; within
value, the application shall precede any literal
<comma> with a <backslash>, which shall be ignored, but
preserves the <comma> as part of value. A <comma> as
the final character, or a <comma> followed solely by
white space as the final characters, in options shall
be ignored. Multiple -o options can be specified; if
keywords given to these multiple -o options conflict,
the keywords and values appearing later in command line
sequence shall take precedence and the earlier shall be
silently ignored. The following keyword values of
options shall be supported for the file formats as
indicated:
delete=pattern
(Applicable only to the -x pax format.) When used
in write or copy mode, pax shall omit from
extended header records that it produces any
keywords matching the string pattern. When used
in read or list mode, pax shall ignore any
keywords matching the string pattern in the
extended header records. In both cases, matching
shall be performed using the pattern matching
notation described in Section 2.13.1, Patterns
Matching a Single Character and Section 2.13.2,
Patterns Matching Multiple Characters. For
example:
-o delete=security.*
would suppress security-related information. See
pax Extended Header for extended header record
keyword usage.
When multiple -odelete=pattern options are
specified, the patterns shall be additive; all
keywords matching the specified string patterns
shall be omitted from extended header records
that pax produces.
exthdr.name=string
(Applicable only to the -x pax format.) This
keyword allows user control over the name that is
written into the ustar header blocks for the
extended header produced under the circumstances
described in pax Header Block. The name shall be
the contents of string, after the following
character substitutions have been made:
┌──────────┬────────────────────────────────────────┐
│ string │ │
│Includes: │ Replaced by: │
├──────────┼────────────────────────────────────────┤
│%d │ The directory name of the file, │
│ │ equivalent to the result of the │
│ │ dirname utility on the translated │
│ │ pathname. │
│%f │ The filename of the file, equivalent │
│ │ to the result of the basename utility │
│ │ on the translated pathname. │
│%p │ The process ID of the pax process. │
│%% │ A '%' character. │
└──────────┴────────────────────────────────────────┘
Any other '%' characters in string produce
undefined results.
If no -o exthdr.name=string is specified, pax
shall use the following default value:
%d/PaxHeaders.%p/%f
globexthdr.name=string
(Applicable only to the -x pax format.) When used
in write or copy mode with the appropriate
options, pax shall create global extended header
records with ustar header blocks that will be
treated as regular files by previous versions of
pax. This keyword allows user control over the
name that is written into the ustar header blocks
for global extended header records. The name
shall be the contents of string, after the
following character substitutions have been made:
┌──────────┬────────────────────────────────────────┐
│ string │ │
│Includes: │ Replaced by: │
├──────────┼────────────────────────────────────────┤
│%n │ An integer that represents the │
│ │ sequence number of the global extended │
│ │ header record in the archive, starting │
│ │ at 1. │
│%p │ The process ID of the pax process. │
│%% │ A '%' character. │
└──────────┴────────────────────────────────────────┘
Any other '%' characters in string produce
undefined results.
If no -o globexthdr.name=string is specified, pax
shall use the following default value:
$TMPDIR/GlobalHead.%p.%n
where $TMPDIR represents the value of the TMPDIR
environment variable. If TMPDIR is not set, pax
shall use /tmp.
invalid=action
(Applicable only to the -x pax format.) This
keyword allows user control over the action pax
takes upon encountering values in an extended
header record that, in read or copy mode, are
invalid in the destination hierarchy or, in list
mode, cannot be written in the codeset and
current locale of the implementation. The
following are invalid values that shall be
recognized by pax:
-- In read or copy mode, a filename or link name
that contains character encodings invalid in
the destination hierarchy. (For example, the
name may contain embedded NULs.)
-- In read or copy mode, a filename or link name
that is longer than the maximum allowed in
the destination hierarchy (for either a
pathname component or the entire pathname).
-- In list mode, any character string value
(filename, link name, user name, and so on)
that cannot be written in the codeset and
current locale of the implementation.
The following mutually-exclusive values of the
action argument are supported:
binary In write mode, pax shall generate a
hdrcharset=BINARY extended header
record for each file with a filename,
link name, group name, owner name, or
any other field in an extended header
record that cannot be translated to the
UTF‐8 codeset, allowing the archive to
contain the files with unencoded
extended header record values. In read
or copy mode, pax shall use the values
specified in the header without
translation, regardless of whether this
may overwrite an existing file with a
valid name. In list mode, pax shall
behave identically to the bypass
action.
bypass In read or copy mode, pax shall bypass
the file, causing no change to the
destination hierarchy. In list mode,
pax shall write all requested valid
values for the file, but its method for
writing invalid values is unspecified.
rename In read or copy mode, pax shall act as
if the -i option were in effect for
each file with invalid filename or link
name values, allowing the user to
provide a replacement name
interactively. In list mode, pax shall
behave identically to the bypass
action.
UTF‐8 When used in read, copy, or list mode
and a filename, link name, owner name,
or any other field in an extended
header record cannot be translated from
the pax UTF‐8 codeset format to the
codeset and current locale of the
implementation, pax shall use the
actual UTF‐8 encoding for the name. If
a hdrcharset extended header record is
in effect for this file, the character
set specified by that record shall be
used instead of UTF‐8. If a
hdrcharset=BINARY extended header
record is in effect for this file, no
translation shall be performed.
write In read or copy mode, pax shall write
the file, translating the name,
regardless of whether this may
overwrite an existing file with a valid
name. In list mode, pax shall behave
identically to the bypass action.
If no -o invalid=option is specified, pax shall
act as if -oinvalid=bypass were specified. Any
overwriting of existing files that may be allowed
by the -oinvalid= actions shall be subject to
permission (-p) and modification time (-u)
restrictions, and shall be suppressed if the -k
option is also specified.
linkdata
(Applicable only to the -x pax format.) In write
mode, pax shall write the contents of a file to
the archive even when that file is merely a hard
link to a file whose contents have already been
written to the archive.
listopt=format
This keyword specifies the output format of the
table of contents produced when the -v option is
specified in list mode. See List Mode Format
Specifications. To avoid ambiguity, the
listopt=format shall be the only or final
keyword=value pair in a -o option-argument; all
characters in the remainder of the option-
argument shall be considered part of the format
string. When multiple -olistopt=format options
are specified, the format strings shall be
considered a single, concatenated string,
evaluated in command line order.
times
(Applicable only to the -x pax format.) When used
in write or copy mode, pax shall include atime
and mtime extended header records for each file.
See pax Extended Header File Times.
In addition to these keywords, if the -x pax format is
specified, any of the keywords and values defined in
pax Extended Header, including implementation
extensions, can be used in -o option-arguments, in
either of two modes:
keyword=value
When used in write or copy mode, these
keyword/value pairs shall be included at the
beginning of the archive as typeflag g global
extended header records. When used in read or
list mode, these keyword/value pairs shall act as
if they had been at the beginning of the archive
as typeflag g global extended header records.
keyword:=value
When used in write or copy mode, these
keyword/value pairs shall be included as records
at the beginning of a typeflag x extended header
for each file. (This shall be equivalent to the
<equals-sign> form except that it creates no
typeflag g global extended header records.) When
used in read or list mode, these keyword/value
pairs shall act as if they were included as
records at the end of each extended header; thus,
they shall override any global or file-specific
extended header record keywords of the same
names. For example, in the command:
pax -r -o "
gname:=mygroup,
" <archive
the group name will be forced to a new value for
all files read from the archive.
The precedence of -o keywords over various fields in
the archive is described in pax Extended Header Keyword
Precedence. If the -o delete=pattern, -o
keyword=value, or -o keyword:=value options are used to
override or remove any extended header data needed to
find files in an archive (e.g., -o delete=size for a
file whose size cannot be represented in a ustar header
or -o size=100 for a file whose size is not 100 bytes),
the behavior is undefined.
-p string Specify one or more file characteristic options
(privileges). The string option-argument shall be a
string specifying file characteristics to be retained
or discarded on extraction. The string shall consist of
the specification characters a, e, m, o, and p. Other
implementation-defined characters can be included.
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.
e Preserve the user ID, group ID, file mode bits
(see the Base Definitions volume of POSIX.1‐2017,
Section 3.169, File Mode Bits), access time,
modification time, and any other implementation-
defined file characteristics.
m Do not preserve file modification times.
o Preserve the user ID and group ID.
p Preserve the file mode bits. Other
implementation-defined file mode attributes may
be preserved.
In the preceding list, ``preserve'' indicates that an
attribute stored in the archive shall be given to the
extracted file, subject to the permissions of the
invoking process. The access and modification times of
the file shall be preserved unless otherwise specified
with the -p option or not stored in the archive. All
attributes that are not preserved shall be determined
as part of the normal file creation action (see Section
1.1.1.4, File Read, Write, and Creation).
If neither the e nor the o specification character is
specified, or the user ID and group ID are not
preserved for any reason, pax shall not set the S_ISUID
and S_ISGID bits of the file mode.
If the preservation of any of these items fails for any
reason, pax shall write a diagnostic message to
standard error. Failure to preserve these items shall
affect the final exit status, but shall not cause the
extracted file to be deleted.
If file characteristic letters in any of the string
option-arguments are duplicated or conflict with each
other, the ones given last shall take precedence. For
example, if -p eme is specified, file modification
times are preserved.
-s replstr
Modify file or archive member names named by pattern or
file operands according to the substitution expression
replstr, using the syntax of the ed utility. The
concepts of ``address'' and ``line'' are meaningless in
the context of the pax utility, and shall not be
supplied. The format shall be:
-s /old/new/[gp]
where as in ed, 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 shall also be permitted to contain <newline>
characters.
Any non-null character can be used as a delimiter ('/'
shown here). Multiple -s expressions can be specified;
the expressions shall be applied in the order
specified, terminating with the first successful
substitution. The optional trailing 'g' is as defined
in the ed utility. The optional trailing 'p' shall
cause successful substitutions to be written to
standard error. File or archive member names that
substitute to the empty string shall be ignored when
reading and writing archives.
-t When reading files from the file system, and if the
user has the permissions required by utime() to do so,
set the access time of each file read to the access
time that it had before being read by pax.
-u Ignore files that are older (having a less recent file
modification time) than a pre-existing file or archive
member with the same name. In read mode, an archive
member with the same name as a file in the file system
shall be extracted if the archive member is newer than
the file. In write mode, an archive file member with
the same name as a file in the file system shall be
superseded if the file is newer than the archive
member. If -a is also specified, this is accomplished
by appending to the archive; otherwise, it is
unspecified whether this is accomplished by actual
replacement in the archive or by appending to the
archive. In copy mode, the file in the destination
hierarchy shall be 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.
-v In list mode, produce a verbose table of contents (see
the STDOUT section). Otherwise, write archive member
pathnames to standard error (see the STDERR section).
-x format Specify the output archive format. The pax utility
shall support the following formats:
cpio The cpio interchange format; see the EXTENDED
DESCRIPTION section. The default blocksize
for this format for character special archive
files shall be 5120. Implementations shall
support all blocksize values less than or
equal to 32256 that are multiples of 512.
pax The pax interchange format; see the EXTENDED
DESCRIPTION section. The default blocksize
for this format for character special archive
files shall be 5120. Implementations shall
support all blocksize values less than or
equal to 32256 that are multiples of 512.
ustar The tar interchange format; see the EXTENDED
DESCRIPTION section. The default blocksize
for this format for character special archive
files shall be 10240. Implementations shall
support all blocksize values less than or
equal to 32256 that are multiples of 512.
Implementation-defined formats shall specify a default
block size as well as any other block sizes supported
for character special archive files.
Any attempt to append to an archive file in a format
different from the existing archive format shall cause
pax to exit immediately with a non-zero exit status.
-X When traversing the file hierarchy specified by a
pathname, pax shall not descend into directories that
have a different device ID (st_dev; see the System
Interfaces volume of POSIX.1‐2017, stat()).
Specifying more than one of the mutually-exclusive options -H and
-L shall not be considered an error and the last option specified
shall determine the behavior of the utility.
The options that operate on the names of files or archive members
(-c, -i, -n, -s, -u, and -v) shall interact as follows. In read
mode, the archive members shall be selected based on the user-
specified pattern operands as modified by the -c, -n, and -u
options. Then, any -s and -i options shall modify, in that order,
the names of the selected files. The -v option shall write names
resulting from these modifications.
In write mode, the files shall be selected based on the user-
specified pathnames as modified by the -n and -u options. Then,
any -s and -i options shall modify, in that order, the names of
these selected files. The -v option shall write names resulting
from these modifications.
If both the -u and -n options are specified, pax shall not
consider a file selected unless it is newer than the file to
which it is compared.
List Mode Format Specifications
In list mode with the -o listopt=format option, the format
argument shall be applied for each selected file. The pax utility
shall append a <newline> to the listopt output for each selected
file. The format argument shall be used as the format string
described in the Base Definitions volume of POSIX.1‐2017, Chapter
5, File Format Notation, with the exceptions 1. through 6.
defined in the EXTENDED DESCRIPTION section of printf, plus the
following exceptions:
7. The sequence (keyword) can occur before a format conversion
specifier. The conversion argument is defined by the value
of keyword. The implementation shall support the following
keywords:
-- Any of the Field Name entries in Table 4-14, ustar
Header Block and Table 4-16, Octet-Oriented cpio
Archive Entry. The implementation may support the cpio
keywords without the leading c_ in addition to the form
required by Table 4-16, Octet-Oriented cpio Archive
Entry.
-- Any keyword defined for the extended header in pax
Extended Header.
-- Any keyword provided as an implementation-defined
extension within the extended header defined in pax
Extended Header.
For example, the sequence "%(charset)s" is the string value
of the name of the character set in the extended header.
The result of the keyword conversion argument shall be the
value from the applicable header field or extended header,
without any trailing NULs.
All keyword values used as conversion arguments shall be
translated from the UTF‐8 encoding (or alternative encoding
specified by any hdrcharset extended header record) to the
character set appropriate for the local file system, user
database, and so on, as applicable.
8. An additional conversion specifier character, T, shall be
used to specify time formats. The T conversion specifier
character can be preceded by the sequence
(keyword=subformat), where subformat is a date format as
defined by date operands. The default keyword shall be
mtime and the default subformat shall be:
%b %e %H:%M %Y
9. An additional conversion specifier character, M, shall be
used to specify the file mode string as defined in ls
Standard Output. If (keyword) is omitted, the mode keyword
shall be used. For example, %.1M writes the single
character corresponding to the <entry type> field of the ls
-l command.
10. An additional conversion specifier character, D, shall be
used to specify the device for block or special files, if
applicable, in an implementation-defined format. If not
applicable, and (keyword) is specified, then this
conversion shall be equivalent to %(keyword)u. If not
applicable, and (keyword) is omitted, then this conversion
shall be equivalent to <space>.
11. An additional conversion specifier character, F, shall be
used to specify a pathname. The F conversion character can
be preceded by a sequence of <comma>-separated keywords:
(keyword[,keyword] ... )
The values for all the keywords that are non-null shall be
concatenated together, each separated by a '/'. The
default shall be (path) if the keyword path is defined;
otherwise, the default shall be (prefix,name).
12. An additional conversion specifier character, L, shall be
used to specify a symbolic link expansion. If the current
file is a symbolic link, then %L shall expand to:
"%s -> %s", <value of keyword>, <contents of link>
Otherwise, the %L conversion specification shall be the
equivalent of %F.
