Format
pax [–cdEnvz][-H|-L][–f archive]
[–o type]
[–s substitute] … [pattern
…]
pax –r [–cdEiknquvz]
[-H|-L] [–f archive]
[–o options …]
[–p string …]
[–s substitute …]
[–V volpat]
[pattern …]
pax –w [–dEituvXz]
[-H|-L] [-W seqparms=parms]
[–b blocksize]
[[–a] [–f archive]]
[–o options …]
[–ssubstitute …]
[–V volpat]
[–x format]
[pathname …]
pax –r –w [–CdDEiklLMntuvX]
[-H|-L][–o options
…] [–p string
…] [–s substitute
…] [pathname …] directory
The pax interchange
format (-x pax), which is a standard UNIX format,
stores all file attributes that extended USTAR (-o saveeext)
or os390 format (-x os390) does. It can
also save and restore file attributes which cannot be handled by any
other format such as: files greater than 8 GB in size, uid
and gid values greater than 2097151 and z/OS®-specific attributes like user
audit and auditor audit flags and file format. The pax interchange
format is supported on z/OS release
8 and later. pax interchange format archives
can be extracted on older systems; however, there will be loss of
information for archived files which have attributes that cannot be
stored in USTAR format. When creating archives that might be extracted
on older z/OS systems, it is
recommended that USTAR (default), extended USTAR(-o saveext) or os390
(-x os390) format be used. When creating archives that will be extracted
on z/OS release 8 systems and
later, the pax format (-x pax)
is the recommended format. See the -x pax option
for more information about preserving extended attributes with the pax
format.
Description
pax reads,
writes, or lists an archive file, or copies directory hierarchies.
An archive file can be a UNIX file
or an MVS™ data set or an MVS data set member. A file stored
inside an archive is called a component file. Similarly, a directory that is stored inside an archive
is called a component directory.
Restrictions: When
using
pax, keep these restrictions in mind.
- pax does not support the use of generation
data groups (GDGs). To use those MVS data
sets, the user must specify the real data set name.
- MVS data sets cannot be specified
for component files.
- When writing to an MVS data
set, the -f archive parameter must be used
to identify the data set.
Included with each component file and directory is recorded
information such as owner and group name, permission bits, file attributes,
and modification time.
You can therefore use a single archive
file to transfer a directory structure from one machine to another,
or to back up or restore groups of files and directories.
Archives
created by pax are interchangeable with
those created with the tar utility. Both
utilities can read and create archives in the default format of the
other (USTAR for pax and TAR for tar, os390 for
both). Additionally, OS390 formatted archives created by pax are
interchangeable with those OS390 formatted archives created by the tar utility.
Archives are generally named with suffixes such as .pax or .tar (or
pax.Z and tar.Z for compressed files), but this is not required.
As
shown in
Format,
pax performs
one of the four archive functions based on the usage of the
–r and
–w options:
- list
- If you do not specify –r or –w,
you are in list mode. In this mode, pax uses
the standard output to display the table of contents of an existing
archive file. The –v (verbose) and –E options
can be used to show the file attributes (to include file tags and
ACLs) and extended attributes of each component. By default, pax displays
all component files and directories contained in the archive. One
or more patterns may be used to display information about specific
components.
- read
- If you specify –r but not –w,
you are in read mode. In this mode, pax reads
an archive file as input and extracts components from the archive.
By default, pax selects all components.
Patterns can also be used to identify specific components to extract.
If the archive contains several components with the same name, pax extracts
each of them with later components overwriting files created by earlier
components with the same name. The –k, –n,
or –u options can be used to control
the extraction of files when multiple files with the same name exist
in the archive or on the file system. pax can
read input archives in cpio, tar, and OS390 format.
When extracted,
if a component does not have a fully qualified path name beginning
with the root (/) directory, its path is assumed to be relative to
the current working directory. The –s or –i options
can be used to dynamically change the path name of extracted components.
Ownership, permissions, file attributes (such as file tags and ACLs),
and extended attributes of the extracted files are discussed
under the –p option.
- write
- If you specify –w but not –r,
you are in write mode. In this mode, pax creates
an archive file that contains the specified path name as components.
If a path name is a directory, pax writes
to the archive file all the files and subdirectories in that directory.
If you do not specify any path name, pax reads
the standard input to get a list of path name to select; the input
should give one path name per line.
The –d, –X,
and –L options can be used to restrict
path name to the current directory or device, or to follow symbolic
links.
The –a (with -w)
option can be used to append to an existing archive.
- copy
- If you specify both –r and –w,
you are in copy mode. In this mode, pax reads
the specified path names and copies them to the target directory.
In this case, the given directory must already exist and you must
be able to write to that directory. If a path name is a directory, pax copies
all the files and subdirectories in that directory as well as the
directory itself. If you do not specify any path name, pax reads
the standard input to get a list of path names to copy; the input
should give one path name per line. copy is
only carried out in the pax (-x
pax) format.
The name of the archive file can be specified
with the –f archive option.
If –f is not used, pax will
read from standard input for the list and read (–r)
functions and will write to standard output for the write (–w)
function.
pax can read input archives
in cpio, tar,
and os390 format. It can also write these
formats; see the –x option.
Patterns
Command-line patterns
are similar to the wildcard constructs described in the sh command.
You can use them to select specific components when reading or listing
an archive.
Slash characters in a path name must be explicitly
matched by using one or more slashes in the pattern; it cannot be
matched by the asterisk (*) or question mark (?) special characters
or by a bracket expression. For example, the pattern "*.c" will
only match files in the archive with name that are not preceded by
a slash. The pattern "*/*.c" will match files in
the archive preceded by a single slash.
Tip: Patterns
should be quoted to prevent the shell from first expanding them. For
example, if the pattern *.h is not quoted, the shell
will first resolve it into the list of files in the current directory
ending with .h. If there are none, the shell will
replace *.h with an empty list and pax will
then list every component in the archive because no pattern is specified.
If one or more .h files are returned by the shell, pax will
list only those components in the archive matching the .h files
found in the current directory.
pax does
not support patterns when writing or copying. However, wildcards can
be used in specifying the path name with the write or copy function
because the shell will first expand them before passing the results
to pax.
The –c option
can be used to select files that do not match the pattern.
Options
The following options might appear
on
pax command lines. Some of them are appropriate
to only some forms of the command, as shown in
Format .
- –a
- Appends specified files or directories to the end of the contents
of an existing archive. If the archive does not already exist, pax creates
it.
Restriction: Compressed archives
and archives residing in MVS partitioned
data sets cannot be appended. Also, archives in OS390 format cannot
be appended to archives in non-OS390 format, and archives in non-OS390
format cannot be appended to archives in OS390 format.
- –b blocksize
- Specifies the block size 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, the block size 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. The default blocksize is 10K for
tar archives and 5K for cpio archives. For ustar, pax, and os390,
the default block size is 32,256 bytes.
The output size will always be in multiples of the block size.
Therefore, the minimum output archive size will be equal to the block
size.
Rule: The block size must be at least 512 bytes
for reading.
- –C
- Causes pax to continue after encountering
an error on the source file system. pax will
print an error message and return a nonzero value after the command
ends. Errors on the target file system (such as out of space or write
errors) will still cause the pax command
to end as it always has.
Restriction: The –C option
is only for pax copy mode.
- –c
- Selects all those files that do not match any of the patterns
given on the command line; this is the opposite of the usual behavior.
If a pattern is not given, then no files will match.
- –D
- Files will not be created sparse in the target directory tree.
Sparse files are those that do not use real disk storage for pages
of file data that contain only zeros, which save on disk space. When
those files are opened and read, the file system returns zeros for
those portions of the files that do not have real disk storage. The
default for pax is to copy all files as
sparse, whether the original file was sparse, if sparse files are
supported on the target file system.
Restriction: The –D option
is only for pax copy mode.
- –d
- Does not traverse directories. A pattern matching a directory
extracts only the directory itself. When creating an archive, a directory
name stores only the directory itself.
- –E
- Same as verbose (–v) output, but
additionally displays extended attributes. See Output for
more information. –o E is equivalent
to pax –E.
- –f archive
- Lets you specify the name of the archive file instead of using
the standard input for list mode, read mode (–r operations),
and the standard output for write mode (–w).
The archive file you specify can be an MVS data
set. For more information, see Specifying MVS data set names in the shell environment.
Tip: Avoid writing to an archive which
is in the directory tree or the set of files being archived. Doing
so causes pax to write the archive to itself
and results in unpredictable results during the write or later during
a read.
- -H
- Follows symbolic links specified on the command line only. When
you specify this option, pax copies the
file pointed to by a symbolic link to an archive. The exception is
if a symbolic link on the command line points to another symbolic
link. A chain of symbolic links is followed to the end. Symbolic
links encountered during tree traversal are not followed; the symbolic
link itself is archived. The default behavior is to archive the symbolic
link itself.
Specifying more than one of the mutually exclusive
options -H and -L is
not considered an error and the last option specified determines the
behavior of the utility.
- –i
- Lets you rename files as pax works.
With extractions, 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. With write operations, 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 change to the name. If you just press <Enter>, pax skips
the file (does not extract or archive it). pax ends
if you enter end–of-file.
If you also specify –s, pax makes
the given substitution before displaying the name of the component.
- –k
- Prevents the overwriting of existing files.
- –L
- Follows symbolic links. When you specify this option, pax copies
the file to which a symbolic link points to the archive. Normally,
only the symbolic link is copied.
Specifying more than one of the
mutually exclusive options -H and -L is
not considered an error and the last option specified determines the
behavior of the utility.
- –l
- Is applicable only when you are in copy mode—that is, when
you are using the –rw format to copy
files to another directory. If you specify –l, pax creates
links to the original files whenever possible, rather than copying
them.
- –M
- Creates empty directories within the target directory tree for
each active mount point encountered within the source directory tree.
pax identifies mount points by checking
if a subdirectory in the source tree is on the same device as the
parent current directory. This behavior is like the current pax
-X option (write out only those files and directories
that are on the same device as their parent directory) except instead
of skipping the subdirectory entirely a corresponding empty directory
is created in the target directory tree. Any contents in the subdirectory
on the source directory tree are ignored.
Restriction: The –M option
is only for pax copy mode.
- –n
- Treats the pattern arguments as ordinary
path names. You can use this option only when you specify –r but
not –w. pax extracts
only the first component with a given path name, 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.
The following set of options controls the use
of z/OS extended USTAR support
for the USTAR, OS390 format and pax format
to preserve, restore, and display z/OS-specific
information such as external links, extended attributes, file tag
information, ACLs, and other information (long link names, for example)
not otherwise supported by the USTAR format. The OS390 and pax format
saves those z/OS specific attributes
by default. For more information about extended USTAR support, see z/OS-extended USTAR support.
- –o keyword[[:]=value][,keyword[[:]=value],
…]
- The value of options shall consist of one or more keywords or
keyword/value pairs.
Multiple keywords or keyword/value pairs
specified to a single -o option can be separated
by a comma or a space unless the environment variable _UNIX03=YES is
used, then this must be a comma-separated list. 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
will be ignored by pax.
If _UNIX03=YES is
not used, then keywords can be preceded with white space and the value
field consists of zero or more characters. Within value, any literal
comma must be preceded with a backslash (\). A comma as the final
character, or a comma followed solely by white space at the end of options will
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
sequences take precedence.
If the
-x pax format is specified, any
of the keywords and values that are defined in
Extended header keywords and are in the following list can be
used in
-o options in
either of two modes:
- keyword=value
- When used in write or copy mode, these keyword-value pairs are
written into the global extended header records of the new archive.
When used in read or list mode, these keyword-value pairs act as if
they were present in the global extended header records of the archive
being read. In both cases, the given value is applied to all files
that do not have a value assigned in their individual extended header
records for the specified keyword.
- keyword:=value
- When used in write or copy mode, these keyword-value pairs are
written into the extended header records of each file in the new archive.
When used in read or list mode, these keyword-value pairs act as if
they were present in the extended header records of each file in the
archive being read. In both cases, the given value overrides any value
for the specified keyword found in the global or file-specific extended
header records.
For example:
pax -r -o "gname:=mygroup" <archive>
the
group name is forced to a new value for all files read from the archive.
The following keywords are supported:
- A
- Displays data for the extended access control list (ACL). For
more information about ACLs, see z/OS UNIX System Services Planning and pax support for access control list (ACL).
Specifying pax -o
A does not automatically turn on the verbose table of
contents format. You must also specify –v to
display the file permission bit settings that are associated with
the file.
- atime=value
- See Extended header keywords.
- charset=value
- See Extended header keywords.
- comment=value
- See Extended header keywords.
- delete=pattern
- (Applicable only to the -x pax format.)
When used in write or copy mode, pax omits
any keywords matching the string pattern from the extended header
records. When used in read or list mode, pax ignores
any keywords matching pattern in the extended
header records. For example:
-o delete=realtime.*
suppresses
information that is related to the realtime keyword.
When multiple -o delete=pattern options
are specified, the patterns are additive; all keywords matching the
specified string patterns are omitted from extended header records
that pax produces. Patterns follow the same
rules given in File name generation.
- E
- Shows extended attributes when displaying the archive table of
contents. Automatically turns on -v. This
option is synonymous with the pax -E option.
- 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 is the contents of string, after
the following character substitutions have been made:
Table 1. String values for exthdr.name string includes: |
Replaced by: |
%d |
The directory name of the file, equivalent to
the result of the dirname utility on the
translated path name. |
%f |
The file name of the file, equivalent to the
result of the basename utility on the translated
path name. |
%p |
The process ID of the pax process. |
%% |
A % character. |
Any other % characters in string
produce the character itself. For instance, %s
prints the character 's'.
If no
-o exthdr.name=string is
specified,
pax uses the following default
value:
%d/PaxHeaders.%p/%f
- from=codeset
-
from=codeset is
typically used with to=codeset.
Converts
data from one code set to another while reading or writing an archive.
This is functionally equivalent to using the iconv utility
to convert each file before or after archiving. This option has the
format where keyword is from and value is
the code set. codeset can
be a code set name known to the system or the numeric coded character
set identifier (CCSID). If a code set name is specified, the numeric
CCSID associated with that name is used. Note that the command iconv
-l lists existing CCSIDs along with their corresponding code
set names.
Two common code set names and their values
are:
- ISO8859-1
- ASCII
- IBM-1047
- EBCDIC
For example, to convert from ASCII to EBCDIC,
use:
-ofrom=ISO8859-1,to=IBM-1047
From EBCDIC
to ASCII, use:
-ofrom=IBM-1047,to=ISO8859-1
For
a complete list of code sets, refer to z/OS XL C/C++ Programming Guide.
You
can omit either the
to or
from keyword.
- When writing an archive, if you specify from,
but omit to, then pax assumes
that you want to write a portable archive and will convert the data
to ISO/IEC 8859-1. If you specify to,
but omit from, then pax will
convert the data from IBM-1047.
- When reading an archive, if you specify from,
but omit to, then pax will
convert the data to IBM-1047. If you specify to,
but omit from, then pax will
convert the data from ISO/IEC 8859-1.
If your input contains a character that is not valid
in the source code set, pax displays a warning
and continues, leaving the character untranslated. If the source code
set contains a character that is not in the destination code set, pax converts
the character to an underscore (_).
By
default, no code set conversion of file contents is done. When making
code set conversions, pax assumes that all
files are text files, because only text files are portable.
- fromfiletag
- For use with –o from=,to=.
Use of –o fromfiletag indicates
that if a component file has a coded character set assigned to it,
then that coded character set is used as the from=codeset,
which overrides the value specified on –o from=,to=.
- gid=value
- See Extended header keywords.
- globexthdr.name=string
- (Applicable only to the -x pax format.)
When used in write or copy mode with the appropriate options, pax creates
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
is the contents of string, after the following character substitutions
have been made:
Table 2. String values
for globexthdr.name 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 the character itself. For instance, %s
prints the character 's'.
If no
-o globexthdr.name=string is
specified,
pax uses the following default
value:
$TMPDIR/GlobalHead.%p.%n
where $TMPDIR
represents the value of the TMPDIR environment variable. If TMPDIR
is not set,
pax uses /tmp.
- gname=value
- See Extended header keywords.
- invalid=action
- (Applicable only to the -x pax format.)
This keyword allows user control over the action pax takes
after encountering values in an extended header record that, in read
or copy mode, are not valid in the destination hierarchy or, in list
mode, cannot be written in the code set and current locale. The following
are values for the invalid keyword that are recognized by pax:
- In read or copy mode, a file name or link name that contains character
encodings that are not valid in the destination hierarchy. For example,
the name might contain embedded NULL characters.
- In read or copy mode, a file name or link name that is longer
than the maximum allowed in the destination hierarchy for either a
path name component or the entire path name.
- In list mode, any character string value (file name, link name,
user name, and so on) that cannot be written in the code set and current
locale.
- bypass
- In read or copy mode, pax bypasses the
file, causing no change to the destination hierarchy. In list mode, pax writes
all requested valid values for the file, but will not write invalid
values.
- rename
- In read or copy mode, pax acts as if
the -i option were in effect for each file
with invalid file name or link name values, allowing the user to provide
a replacement name interactively. In list mode, pax behaves
identically to the bypass action.
- UTF-8
- When used in read, copy, or list mode and a file name, link name,
owner name, or any other field in an extended header record cannot
be translated from the pax UTF-8 code set
format to the code set and current locale, pax uses
the actual UTF-8 encoding for the name.
- write
- In read or copy mode, pax writes the
file, translating the name, regardless of whether this may overwrite
an existing file with a valid name. In list mode, pax behaves
identically to the bypass action.
If no -o invalid= option
is specified, pax acts as if -o
invalid= bypass were specified. Any overwriting of existing
files that might be allowed by the -o invalid= actions
is subject to permission (-p) and modification
time (-u) restrictions, and is suppressed
if the -k option is also specified.
- linkdata
- (Applicable only to the -x pax format.)
In write mode, pax writes 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.
- linkpath=value
- See Extended header keywords.
- listopt=format
- This keyword specifies the output format of the table of contents
produced when the -v option is specified
in list mode. To avoid ambiguity, listopt= format must
be only or final keyword in the -o options argument.
All characters in the remainder of the -o options argument
are considered part of the format string.
When multiple -o listopt=format options
are specified, the format strings are considered a single, concatenated
string, evaluated in command line order.
To
ensure proper data display, use the proper conversion specifier character
for the field being displayed for numeric data. For example, the size
field on z/OS systems is often
a long data type. Attempting to display the size field using a conversion
specifier for a smaller data type, for example %d, will result in
a zero being displayed instead of the contents of the size field.
- mtime=value
- See Extended header keywords.
- noext
- See -o saveext | noext.
- path=value
- See Extended header keywords.
- realtime.any=value
- See Extended header keywords.
- security.any=value
- See Extended header keywords.
- saveext | noext
- For USTAR and OS390-formatted archives, controls whether extended
USTAR support is enabled (saveext) or disabled
(noext). noext is
the default behavior for USTAR format when writing an archive.
The
saveext option
is the default behavior for OS390 format when writing an archive.
It is the default behavior when extracting or listing files from
the archive. It is also the default to save extended attributes and
external links. To list attributes such as ACLs or file tags,
-o
A and
-o T option must be
used. This option has no effect for non-USTAR format. For more information
about extended USTAR support, see
z/OS-extended USTAR support.
Table 3. USTAR defaultsAction |
USTAR default |
Writing, copying |
-noext |
Extracting, listing |
-saveext |
- saveext
- During archive writing, saveext causes pax to
preserve extended USTAR information. During archive listing, saveext causes pax to
display extended USTAR information. During archive reading, saveext enables pax to
restore extended USTAR information. To restore certain information,
the user must also have the appropriate privileges and have specified
the corresponding options. For example, in order to restore extended
attributes, -px must be specified and to
restore ACLs -pA must be specified. The external links and extended
attributes are saved by default for USTAR and OS390 format. The file
attributes requiring special headers, such as long links, file tags,
and ACLs, need the -o saveext to
be specified for USTAR (OS390 uses -o saveext by
default). The environment variable _OS390_USTAR=Y can also be used
to turn on the support. For more information about extended USTAR
support, see z/OS-extended USTAR support.
- noext
- When creating archives, does not preserve extended USTAR information.
When reading or listing an archive, ignore any extended USTAR support
(such as extended attributes, long links, external links, file tags,
and ACLs) encoded within the archive. If an archive contains z/OS special header files, these
will be displayed or restored (or both) as regular files. Special
header files are described in z/OS-extended USTAR support).
Restriction: The pax (-x
pax) format does not recognize the noext option.
- setfiletag
- For use with -o from=,to=.
Using -o
setfiletag will tag component files that have not already
been tagged.
If a file is untagged (TXTFLAG = OFF, CCSID =
0), then it is automatically stored with TXTFLAG = ON and with CCSID
= to the target code set.
For files that are already not untagged, -o
setfiletag does not change the default behavior. The
target code set and TXTFLAG values are left as is. For example, a
file tagged as mixed will have TXTFLAG = OFF and CCSID <> 0. UNIX will not automatically force
TXTFLAG = ON because it does not want to override the user's reason
for making the file mixed.
- size=value
- See Extended header keywords.
- times
- (Applicable only to the -x pax format.)
When used in write or copy mode, pax includes atime and mtime extended
header records for each file.
- T
- Displays file tag information. Similar to ls –T and chtag output.
Does not automatically turn on verbose (–v)
in the same way that ls –T does not
automatically turn on its –l (long
listing) option. When used without –v,
only the file tag information and file names are displayed.
Example: When
used without
–v:
/tmp> pax -o T -f asciitagged.pax
m ISO8859-1 T=off text_am
t ISO8859-1 T=on text_at
- untagged T=off text_au
This option can be
used with –v or –o
E to display additional verbose output.
Example: To display additional verbose output:
/tmp> pax -o T -vf asciitagged.pax
m ISO8859-1 T=off -rw-r--r-- 1 SteveS Kings 9 Apr 30 22:31 text_am
t ISO8859-1 T=on -rw r--r-- 1 SteveS Kings 9 Apr 30 22:31 text_at
- untagged T=off -rw-r--r-- 1 SteveS Kings 9 Apr 30 22:06 text_au
- to=codeset
-
to=codeset is
typically used with from=codeset.
Converts data to another code set while reading or writing
an archive. This is functionally equivalent to using the iconv utility
to convert each file before or after archiving. This option has the
format where keyword is to and value is
a code set. codeset can be a code set name
known to the system or the numeric coded character set identifier
(CCSID). If a code set name is specified, the numeric CCSID associated
with that name is used. Note that the command iconv -l lists
existing CCSIDs along with their corresponding code set names.
Two
common code set names and their values are:
- ISO8859-1
- ASCII
- IBM-1047
- EBCDIC
For example, to convert from ASCII to EBCDIC,
use:
-ofrom=ISO8859-1,to=IBM-1047
From
EBCDIC to ASCII, use:
-ofrom=IBM-1047,to=ISO8859-1
For
a more complete list of code sets, refer to z/OS XL C/C++ Programming Guide.
You
can omit either the
to or
from keyword.
- When writing an archive, if you specify from,
but omit to, then pax assumes
that you want to write a portable archive and will convert the data
to ISO/IEC 8859-1. If you specify to,
but omit from, then pax will
convert the data from IBM-1047.
- When reading an archive, if you specify from,
but omit to, then pax will
convert the data to IBM-1047. If you specify to,
but omit from, then pax will
convert the data from ISO/IEC 8859-1.
If your input contains a character that is not valid
in the source code set, pax displays a warning
and continues, leaving the character untranslated. If the source code
set contains a character that is not in the destination code set, pax converts
the character to an underscore (_).
By
default, no code set conversion of file contents is done. pax assumes
that all files are text files, since only text files are portable.
- uid=value
- See Extended header keywords.
- uname=value
- See Extended header keywords.
- ZOS.any=value
- See Extended header keywords.
- –p string
- Specifies which file characteristics to restore. By default, pax will
only restore the access time (if it is stored in the archive) and
modification time of each component file, and the access permissions
(mode) as modified by the current umask, that is, they will only be
restored entirely when the umask is 000. Currently only pax format
archives are capable of storing the access time. Other archive formats
use the modification time as the access time.
To store the access
time in a pax format archive, you must specify -o times when
the archive is created or you can manually specify a value for a common
access time for all the files in the archive with the -o option
used with the atime keyword on archive creation
or extraction. The file tag information, external links, and links
whose target exceed 100 characters are also restored by default. Only
file attributes that are available in the archive being read can be
restored. See the -x option, the -o saveext|noext option,
and the file format descriptions in File formats to
understand the limitations of the archive formats.
string can
consist of any combination of the following characters:
- A
- Restores ACL data.
- a
- Does not preserve file access times.
- e
- Preserves the user ID, group ID, file mode, access time, modification
time, extended attributes, and ACL entries. Prior to z/OS 1.8,
audit flags and file format (line end) attributes were not restored
because they are not available in any archive format. The extended
attributes are the apsl flags that are set
by the extattr command. A pax format
archive can be used to store the audit flags and file format, and -p
e will restore them when available.
- m
- Does not preserve file modification times.
- o
- Preserves the user ID and group ID.
- p
- Preserves the file mode: access permissions (without modification
by umask), set-user-ID bit, set-group-ID bit, and sticky bit.
pax restores
access permissions by default. If _UNIX03=YES extracted
files will have permissions of 0666 (modified by umask) unless -p
p or -p e are used.
- W
- Preserves user-requested audit attributes and auditor-requested
audit attributes and the file format . The invoking user id must
have the AUDITOR attribute set in the system security product to
successfully set auditor-requested audit attributes.
- x
- Preserves extended attributes. The extended attributes are the apsl flags
that are set by the extattr command.
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 set-user-ID
and set-group-ID bits of the file mode.
- –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 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 name using a substitution command substitute.
This is similar to the substitution command of the ed text
editor. The full option has the form:
–s#bregexp#string#[gp]
where bregexp is
a basic regular expression and string is
a string that pax is to insert in place
of matches for the regular expression. string can
contain an ampersand & (standing for the string
matching bregexp), or \1, \2,
and so on (with the meanings defined in regexp),
for subexpression matching. The # is used as
the delimiter character separating bregexp and string.
You can use any non-null character instead. There cannot be any space
between -s and the delimiter character.
Normally, –s replaces
only the first match for bregexp. 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
There
might 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, pax resets
the access time to that prior to pax's access.
- –u
- Compares component dates to dates of existing files with the same
name. When extracting components with –r (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,
when copying files with –rw (copy
mode), pax does not overwrite an existing
file if the existing file is newer than the one being copied.
In
a command that uses –w but not –r (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.
- –V volpat
- Provides automatic
multivolume support. pax writes output to
files the names of which are formatted with volpat.
It replaces any occurrence of # in volpat with
the current volume number. When you invoke pax with
this option, it asks for the first number in the archive set, and
waits for you to type the number and a carriage return before proceeding
with the operation. pax issues the same
sort of 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 ends pax.
- –v
- Lists path name on the standard error stream just before beginning
to process the files or directories, but after any –i,
or –s options have had their effect.
In list mode (neither –r nor –w is
specified), pax displays a “verbose”
table of contents; this verbose format shows information about the
components in the same format used by the ls command. See Output for more information.
- -W seqparms=parms
- Specifies the parameters needed to create a sequential data set
if one does not already exist. You can specify the RECFM, LRECL, BLKSIZE,
and SPACE in the format that fopen() function uses.
SPACE=(units,(primary,secondary) where
the following values are supported for units:
- Any positive integer indicating BLKSIZE
- CYL (mixed case)
- TRK (mixed case)
Space can be specified as follows:
SPACE=(500,(100,500)) units, primary, secondary
SPACE=(500,100) units and primary only
The fopen()
arguments: LRECL specifies the length, in bytes, for fixed-length
records and the maximum length for variable-length records. BLKSIZE
specifies the maximum length, in bytes, of a physical block of records.
RECFM refers to the record format of a data set and SPACE indicates
the space attributes for MVS data
sets. For example:
pax -W "seqparms='RECFM=U,space=(500,100)'" -wf "//'target.dataset'" source
For
information about specifying these parameters, see z/OS XL C/C++ Programming Guide.
- –w
- Writes files to standard output in the specified archive format.
- –X
- Writes out only those files that are on the same device as their
parent directory. However, it will not copy a directory currently
used as a mount point. The user must either unmount the file system
from that mount point or copy the directory manually.
- –x format
- Specifies a file format for an output archive. The format argument
can be:
- cpio
- The ASCII format used by the cpio command.
- cpiob
- The binary format used by cpio.
- os390
- The OS390 format, which has all the support for saving and restoring
extended USTAR support such as special headers, external links, and
long links. This format is only supported on z/OS systems.
- pax
- The pax interchange format which, like
os390 format (-x os390) and extended USTAR
(-o saveext), saves or restores file attributes
that cannot be stored in the USTAR header format such as ACLs, external
links, long link names, long path names, file tags and extended attributes.
Additionally,
the pax interchange format can save and
restore file attributes that cannot be handled by any other format
such as files greater than 8 GB in size, uid
and gid values greater than 2097151 and z/OS-specific attributes like user
audit and auditor audit flags and file format. To restore certain
information, the user must also have the appropriate privileges and
have specified the corresponding options. See -p for
options for restoring file attributes.
In copy mode, pax shall
behave as if it were using the pax interchange
format.
- tar
- The historical format of tar files.
- ustar
- The USTAR format used by the tar command.
It is the default for format.
To preserve
information about extended attributes, external links, and link names
greater than 100 characters, ustar with either the _OS390_USTAR=Y environment
variable or the -o saveext option
can be used. You can also use the -x os390 or -x
pax option to store these attributes.
Guideline: When
creating archives that might be extracted on older z/OS systems, use the USTAR, extended USTAR
(-o saveext) or
os390 format. If the archives will only be extracted on z/OS release 8 systems and later, the pax format (-x
pax) is the recommended format.
- –z
- For write or read mode, performs Lempel-Ziv compression. –z cannot be
used when appending (–a) to an existing
archive.
It is recommended that, when creating archive files using the –f option,
the archive name be suffixed with a .Z to identify it as a compressed
file and to facilitate it being processed by uncompress (if needed).
For
reads, –z is functionally equivalent
to first uncompressing the archive using the uncompress utility and
then reading it. This option is not required when reading a compressed
archive. pax will automatically detect that
the archive is compressed. It might be useful, however, to use –z to
confirm that the archive is compressed; you will receive an error
message if you specify –z on an archive
that is not compressed.
Output
When the
–v or
–E option
is used in list mode,
pax produces a verbose
table of contents for the archive. The output for
–v is
similar to the output from the
ls –l command
with the following exceptions:
- The notation:
pathname == linkname
indicates
that linkname is a hard link of pathname.
- For symbolic and external links, pax output
always shows a file size of 0.
The output from the
–E option
has the same format as
–v and additionally
displays a column showing the extended attributes:
- a
- Program runs APF-authorized if linked AC=1
- p
- Program is considered program-controlled
- s
- Program runs in a shared address space
- l
- Program is loaded from the shared library region. (l is
a lowercase L, not an uppercase i.)
- –
- Attribute not set
The format of the pax –E output
is variable in length and is extended as necessary to display additional
file characteristics that are not supported by pax –v (ls
–l).
Usage notes
- On the z/OS system,
superuser privileges or read access to the appropriate FACILITY class
resources are required to create character special files, restore
user and group names, and to set certain extended attributes (read
access to the corresponding FACILITY class resources).
- The POSIX 1003.1 standard defines formats for pax, tar,
and cpio archives that limit the UIDs and
GIDs that can be stored to the following maximum values:
Table 4. Maximum UID and GID values for tar, USTAR, cpio
and pax Format |
Maximum UID and GID values |
tar, USTAR |
2,097,151 |
cpio |
262,143 |
pax |
2,147,483,647 |
Values larger than these will not be properly restored for tar and cpio formatted
archives. For USTAR formatted archives, because the user and group
names are also stored in the archive, the correct UID and GID will
be restored only if the name is defined on the target system.
- In historical UNIX standard
formats, for pax and tar archives,
the length of a link file target is limited to 100 characters or less.
If hard links exist, the target is the first occurrence of the hard
link that is saved in the archive. Subsequent hard links refer to
the first instance. You can use the extended USTAR support provided
by pax and tar to
save the long hard links when the archives are created, and to restore
them when the archives are read. As of z/OS V1R8,
the pax format as defined by the current UNIX standard provides a means to
save and restore long link names that can be transferred between other
(including non-z/OS) UNIX platforms.
For more information, see -x pax.
- In historical UNIX standard
formats, the size of a file that can be stored in a pax and tar
archive was limited to 8 gigabytes. As of z/OS V1R8, the pax format
archive allows files greater than 8 gigabytes to be archived. For
more information, see -x pax.
- When transferring archives between z/OS systems
and other UNIX systems, note the following:
- Archive files must always be transferred in binary mode, even
if the archives contain only text files. Common ways of transferring
files include FTP, the cp shell command,
and the OPUT and OGET TSO/E commands.
- You might need to convert text files from EBCDIC to ASCII (or
some other character set). The pax -o option
can be used to convert text files while an archive is being created
or being restored. You can use the iconv utility
to convert files before they are stored in the archive or after restoring
them from an archive.
- Automatic conversion on files with file tag information is disabled
when reading files during creation of an archive or during writes
while extracting files from an archive. That is, the settings of system
and environment variables that turn automatic conversion on and off
will have no effect on the reading and writing of files by pax.
File tagging
When the
–o from=,to= option
is used to perform translation, the default behavior for storing the
file tag information is as follows:
- –w (write)
-
For files that are tagged, the CCSID preserved in the archive
is set to the CCSID of the to=codeset argument.
Files that are untagged (TXTFLAG = OFF and CCSID = 0) will not have
file tag information stored. The –o setfiletag option
can be used to force the tagging of files which are not already tagged.
When
a file in the archive is tagged with a different CCSID than the from=codeset,
an error message is generated. However, pax will
continue processing. Because this situation indicates a probable corruption
of data, upon completion, pax will issue
a nonzero return code. To avoid this situation, the –o
fromfiletag option can be used. It causes pax to
use the CCSID of the file instead of the one specified on the –o from=,to= option.
- –r (read)
-
For
files that are tagged, the TXTFLAG value is restored to the value
preserved in the archive (ON or OFF), but the CCSID of the target
file is altered to the to=codeset CCSID.
For example, a file tagged as mixed will have TXTFLAG
= OFF and CCSID ≠ 0. z/OS UNX
will not automatically force TXTFLAG = ON because it does not want
to override the user's reason for making the file mixed.
The
default behavior for files in the archive that are untagged will not
change, and the target file will also be set to untagged. The –o
setfiletag option can be used to force the tagging of
files that do not have filetag information associated with them in
the archive.
If the target file already exists, its filetag
information is ignored.
When a file in the archive is tagged
with a different CCSID than the from=codeset,
an error message will be generated. However, pax will
continue processing. Because this situation indicates a probable corruption
of data, upon completion, pax issues a nonzero
return code. The –o fromfiletag option
can be used to avoid this situation. It causes pax to
use the CCSID of the file rather than the one specified on the –o from=,to= option.
- –wr (copy)
-
If
the source files are tagged, then the target file will have its CCSID
set to the CCSID of the to=codeset CCSID.
If the target already exists, then its TXTFLAG values are ignored;
the source file is used to determine the TXTFLAG setting of the target
and will override whatever the TXTFLAG settings are of the target.
Like –r and –w,
when the CCSID of the source file is different from the from=codeset CCSID,
a warning message is generated and, upon completion, pax issues
a nonzero return code. The –o fromfiletag option
can be used to avoid this situation. It causes pax to
use the CCSID of the file rather than the one specified on the –o from=,to= option.
Extended header keywords
The
following extended header keywords are applicable only in the
-x
pax format.
- atime
- The file access time for the following files, equivalent to the
value of the st_atime member of the stat structure for a file. The
access time shall be restored if the process has the appropriate privilege
required to do so.
- charset
- The name of the character set used to encode the data in the following
files. The entries in this table are defined to refer to known standards
and the charset value used to represent
each:
The encoding is included in an extended header for information
only; when pax is used as described, it
does not translate the file data into any other encoding. The BINARY
entry indicates unencoded binary data.
Table 5. Charset
standards<value> |
Formal standard |
ISO-IR 646 1990 |
ISO/IEC 646:1990 |
ISO-IR 8859 1 1998 |
ISO/IEC 8859-1:1998 |
ISO-IR 8859 2 1999 |
ISO/IEC 8859-2:1999 |
ISO-IR 8859 3 1999 |
ISO/IEC 8859-3:1999 |
ISO-IR 8859 4 1998 |
ISO/IEC 8859-4:1998 |
ISO-IR 8859 5 1999 |
ISO/IEC 8859-5:1999 |
ISO-IR 8859 6 1999 |
ISO/IEC 8859-6:1999 |
ISO-IR 8859 7 1987 |
ISO/IEC 8859-7:1987 |
ISO-IR 8859 8 1999 |
ISO/IEC 8859-8:1999 |
ISO-IR 8859 9 1999 |
ISO/IEC 8859-9:1999 |
ISO-IR 8859 10 1998 |
ISO/IEC 8859-10:1998 |
ISO-IR 8859 13 1998 |
ISO/IEC 8859-13:1998 |
ISO-IR 8859 14 1998 |
ISO/IEC 8859-14:1998 |
ISO-IR 8859 15 1999 |
ISO/IEC 8859-15:1999 |
ISO-IR 10646 2000 |
ISO/IEC 10646:2000 |
ISO-IR 10646 2000 UTF-8 |
ISO/IEC 10646, UTF-8 encoding |
BINARY |
None |
- comment
- A series of characters used as a comment. All characters in the
value field are ignored by pax.
- gid
- The group ID of the group that owns the file, expressed as a decimal
number using digits from ISO/IEC 646. This record overrides the gid
field in the following header blocks.
When used in write or copy
mode, pax includes a gid extended header
record for each file whose group ID is greater than 2097151 (octal
7777777).
- gname
- The group of the following files, formatted as a group name in
the group database. This record overrides the gid and gname fields
in the following header blocks, and any gid extended
header record.
When used in read, copy, or list mode, pax translates
the name from the UTF-8 encoding in the header record to the character
set appropriate for the group database on the receiving system. If
any of the UTF-8 characters cannot be translated, and if the -o
invalid=UTF-8 option is not specified, the results are
undefined as if -o invalid=bypass were specified.
When
used in write or copy mode, pax includes
a gname extended header record for each
file whose group name cannot be represented entirely with the letters
and digits of the portable character set.
- linkpath
- The path name of a link being created to another file, of any
type, previously archived. This record overrides the linkname field
in the following USTAR header blocks.
The following USTAR header
block determines the type of link created, whether hard or symbolic.
In the latter case, the linkpath value is
the contents of the symbolic link. pax translates
the name of the link (contents of the symbolic link) from the UTF-8
encoding to the character set appropriate for the local file system.
When
used in write or copy mode, pax includes
a linkpath extended header record for each
link whose path name cannot be represented entirely with the members
of the portable character set other than NULL.
- mtime
- The file modification time of the following files, equivalent
to the value of the st_mtime member of the stat structure for a file.
This record overrides the mtime field in
the following header blocks. The modification time is restored if
the process has the appropriate privilege to do so.
- path
- The path name of the following files. This record overrides the
name and prefix fields in the following header blocks. pax translates
the path name of the file from the UTF-8 encoding to the character
set appropriate for the local file system.
When used in write or
copy mode, pax includes a path extended
header record for each file whose path name cannot be represented
entirely with the members of the portable character set other than
NULL.
- realtime.any
- The keywords prefixed by realtime. are
reserved for future POSIX realtime standardization. pax recognizes
but silently ignores them.
- security.any
- The keywords prefixed by security. are
reserved for future POSIX security standardization. pax recognizes
but silently ignores them.
- size
- The size of the file in octets, expressed as a decimal number
using digits from ISO/IEC 646. This record overrides the size field
in the following header blocks.
When used in write or copy mode, pax automatically
includes a size of extended header record for each file with a size
value greater than 8589934591 (octal 77777777777).
As with
other keywords, the user can manually set this value by using -o
size=value or -o
size:=value. However, it is
strongly recommended this not be done. Creating a global or extended
size record for the size extended record keyword can cause failures
or data corruption when used in read or write mode. size extended
records are ignored by pax in copy mode.
- uid
- The user ID of the user that owns the file, expressed as a decimal
number using digits from ISO/IEC 646. This record overrides the uid field
in the following header blocks.
When used in write or copy mode, pax includes
a uid extended header record for each file
whose owner ID is greater than 2097151 (octal 7777777).
- uname
- The owner of the following files, formatted as a user name in
the user database. This record overrides the uid and uname fields
in the following header blocks, and any uid extended
header record.
When used in read, copy, or list mode, pax translates
the name from the UTF-8 encoding in the header record to the character
set appropriate for the user database on the receiving system. If
any of the UTF-8 characters cannot be translated, and if the -o
invalid=UTF-8 option is not specified, the results are
as if -o invalid=bypass were specified.
When
used in write or copy mode, pax includes
a uname extended header record for each
file whose user name cannot be represented entirely with the letters
and digits of the portable character set.
- ZOS.acls
- The extended access control lists (extended ACLs) of the following
files.
When used in write or copy mode,
pax includes
a ZOS.acls record for each file which has extended ACLs set. Values
of the
ZOS.acls keyword have the following format
[d[efault]: | f[default]:]u[ser]:uid:perm
[d[efault]: | f[default]:]g[roup]:gid:perm
where:
- d[efault]
- If specified, extended ACL refers to directory default ACL
- f[default]
- If specified, extended ACL refers to file default ACL
- u[ser]
- Extended ACL refers to a particular numeric user ID (UID) or user
name
- g[roup]
- Extended ACL refers to a particular numeric group ID (GID) or
group name
- uid
- User name or numeric user ID (UID)
- gid
- Group name, or numeric group ID (GID)
- perm
- Permissions specified either in absolute form (string rwx with
- as a placeholder or octal form
Syntax examples:
-o ZOS.acls=user:billy:r-x
-o ZOS.acls=g:cartoons:r
In the next example, note that
the multiple entries in the value are comma-separated. However, because
these literal commas are in a
-o value,
they must be preceded by a backslash since commas are used to delimit
keyword-value pairs regardless of whether the value is enclosed in
quotation marks.
-o
ZOS.acls=user:user1:r-x\,group:thegang:r--\,user:user2:r-x
\,d:user:user1:r-x\,d:group:thegang:r--\,d:user:user2:r-x
- ZOS.taginfo
- The value for the ZOS.taginfo keyword
is composed of a text flag (txtflag) and a coded
character set and allows the user to modify the taginfo associated
with the file.
The txtflag indicates whether a file contains uniformly
encoded or non-uniformly encoded text data. Values for txtflag are
0 (indicating txtflag is OFF) or 1 (indicating txtflag is ON). If
the txtflag is 1 (ON), it indicates that the specified file contains
pure (uniformly encoded) text data. For files that contain binary,
mixed or unknown data, the txtflag is 0 (OFF).
The coded character set represents the code
set in which text data is encoded. The code set can be used for
uniformly encoded text files or files that contain mixed text/binary
data. It can be a code set name known to the system or the numeric
coded character set identifier (CCSID). If a code set name exists,
the numeric CCSID associated with that name
will be used).
When used in write or copy mode, pax includes
a ZOS.taginfo extended header record for
each file for which txtflag is 1 (ON) or the file is
not untagged.
The command
iconv -l lists
existing CCSIDs along with their corresponding code set
names. Values of the
ZOS.taginfo keyword
have the following format:
0 [ccsid]
1 ccsid
Syntax examples:
-o ZOS.taginfo=0
-o ZOS.taginfo="1 819"
-o ZOS.taginfo="0 1208"
-o ZOS.taginfo="1 1047"
- ZOS.useraudit
- Indicates the user-requested audit attributes of the specified
files or directories. Audit attributes determine whether accesses
to a file are audited by the system authorization facility (SAF) interface.
When used in write or copy mode, pax includes
a ZOS.useraudit record for each file which
the user-requested audit attributes are anything other than auditing
read, write and execute failures on the file.
The value of
the
ZOS.useraudit keyword is a sequence
of three characters, each of which can be one of the following four
characters. The character in the first position represents the audit
properties for read operations on the corresponding file, the second
represents audit properties for write operations on the corresponding
file and the third character represents audit properties for execute
operations on the corresponding file.
- -
- Do not audit
- f
- Audit failures
- s
- Audit successes
- a
- Audit both successes and failures
Syntax examples:
-o ZOS.useraudit=ffa
-o ZOS.useraudit=ssa
-o ZOS.useraudit=sf-
- ZOS.auditoraudit
- Indicates the auditor-requested audit attributes of the specified
files or directories. Audit attributes determine whether accesses
to a file are audited by the system authorization facility (SAF) interface.
When used in write or copy mode, pax includes
a ZOS.auditoraudit record for each file
which the auditor-requested audit attributes are set on the file.
The
value of the
ZOS.auditoraudit keyword is
a sequence of three characters, each of which can be one of the following
four characters. The character in the first position represents the
audit properties for read operations on the corresponding file, the
second represents audit properties for write operations on the corresponding
file and the third character represents audit properties for execute
operations on the corresponding file.
- -
- Do not audit
- f
- Audit failures
- s
- Audit successes
- a
- Audit both successes and failures
Syntax examples:
-o ZOS.auditoraudit=ffa
-o ZOS.auditoraudit=ssa
-o ZOS.auditoraudit=sf-
- ZOS.filefmt
- Specifies if a file is binary or text and for text files, specifies
the end-of-line delimiter. For format you can specify:
- not
- Not specified
- bin
- Binary data
- rec
- Record. (File data consists of records with prefixes. The record
prefix contains the length of the record that follows. From the shell
command perspective, files with this format are treated as if they
were binary files.)
Or the following text data delimiters: - nl
- Newline character
- cr
- Carriage return
- lf
- Line feed
- crlf
- Carriage return followed by line feed
- lfcr
- Line feed followed by carriage return
- crnl
- Carriage return followed by a newline character
Restriction: The rec value
for ZOS.filefmt is only available on z/OS V1R12 and later. Therefore,
if an object with the rec file format is
restored on an earlier release, the rec file
format information will be lost.
- ZOS.extattr
- The value of this keyword is a 4-character string that specifies
the extended attributes for files to allow executable files to be
marked so they run APF authorized, as a program controlled executable,
or not in a shared address space.
- The first character of the value specifies whether the program
runs APF authorized and is either 'a' or '-'.
- The second character of the value specifies whether the program
is considered program controlled and is either 'p 'or '-'.
- The third character of the value specifies whether the program
runs in a shared address space and is either 's' or '-'.
- The fourth character of the value specifies whether the program
file is loaded from the shared library region and is either 'l' or
'-'.
- a
- The program runs APF-authorized if linked AC=1.
- p
- The program is considered program controlled.
- s
- The program runs in a shared address space.
- 1
- The program file is loaded from the shared library region.
- -
- The attribute is not set
Syntax examples:
-o ZOS.extattr=apsl
-o ZOS.extattr=ap-l
-o ZOS.extattr=-p--
Extended header keyword precedence
(Applicable
only to the -x pax format.)
This
topic describes the precedence in which the various header records
and fields and command-line options are selected to apply to a file
in the archive. When pax is used in read
or list modes, it determines a file attribute in this sequence:
- If -o delete=keyword-prefix is
used, the affected attribute is determined from step 7 if applicable, or ignored otherwise.
- If -o keyword:= is used with no value
specified, the affected attribute is ignored.
- If -o keyword:=value is
used, the affected attribute is assigned the value.
- If a keyword exists in a file-specific
extended header record, the affected attribute is assigned the value.
When extended header records conflict, the last one given in the header
takes precedence.
- If -o keyword=value is
used, the affected attribute is assigned the value.
- If a keyword exists in a global extended
header record, the affected attribute is assigned the value. When
global extended header records conflict, the last one given in the
global header takes precedence.
- Otherwise, the attribute is determined from the USTAR
header block.
List mode format specifications
In list
mode with the -o listopt=format option,
the format argument is applied for each selected file. The pax utility
appends a newline character to the listopt output for each selected
file. The format argument is used as the format string with the following
exceptions:
- A <space> character in the format string, in any context
other than a flag of a conversion specification, is treated as an
ordinary character that is copied to the output.
- In addition to the escape sequences \\,\a, \b, \f, \n, \r, \t,
and \v, the escape sequence \ddd, where ddd is
a one-, two-, or three-digit octal number, is written as a byte with
the numeric value specified by the octal number.
- Output from the d or u conversion specifiers is not preceded or
followed with s not specified by the format operand.
- Output from the o conversion specifier is not preceded with zeros
that are not specified by the format operand.
- The sequence (keyword) can occur before a format conversion specifier.
The conversion argument is defined by the value of keyword. The following
keywords are supported:
Any of the Field Name entries in USTAR
Header Block and Octet-Oriented cpio Archive Entry. The implementation
supports the cpio keywords without the leading
c_ in addition to the form required by Values for cpio c_ mode Field.
Any
keyword defined for the extended header in Extended header keywords.
Any
keyword provided as an implementation-defined extension within the
extended header defined in Extended header keywords. For
example, the sequence "%(charset)s" is the string value of the name
of the character set in the extended header.
To ensure proper
data display be sure to use the proper conversion specifier character
for the field being displayed for numeric data. For example, the size
field on z/OS systems ID is
often a long long data type. Attempting to display the size field
using a conversion specifier for a smaller data type, for example
%d, will result in a zero being displayed instead of the contents
of the size field.
The result of the keyword conversion argument
is the value from the applicable header field or extended header,
without any trailing NULs. All keyword values used as conversion arguments
are translated from the UTF-8 encoding to the character set appropriate
for the local file system, user database, and so on, as applicable.
- An additional conversion specifier character, T, is 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 is mtime and the
default subformat is:
%b %e %H:%M %Y
- An additional conversion specifier character, M, is used to specify
the file mode string as defined in ls Standard Output. If (keyword)
is omitted, the mode keyword is used. For example, %.1M writes the
single character corresponding to the entry type field of the ls -l
command.
- An additional conversion specifier character, D, is used to specify
the device for block or special files.
- If the use of D is applicable, the format is "devmajor,devminor".
- If the use of D is not applicable and (keyword) is specified,
then this conversion is equivalent to %(keyword)u.
- If the use of D is not applicable and (keyword) is omitted, then
this conversion is equivalent to <space>.
- An additional conversion specifier character, F, is used to specify
a path name. 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 are concatenated, each
separated by a /. The default is (path) if the keyword path is defined.
Otherwise, the default is (prefix,name).
- An additional conversion specifier character, L, is used to specify
a symbolic link expansion. If the current file is a symbolic link,
then %L expands to:"%s -> %s", value of keyword,
contents of link.
Otherwise, the %L conversion specification is
the equivalent of %F.
z/OS-extended USTAR support
OS390
archive format stores all the extended USTAR attributes by default
(the
-o options do not apply). By default,
the
z/OS implementation
of
pax and
tar provide
extended support with the USTAR format to preserve and restore
z/OS-specific
file attributes and other information not otherwise supported due
to limitations with the USTAR format. The OS390 format also stores
these by default. Examples of these include:
- External links
- Extended file attributes (such as program-controlled and APF-authorized).
The extended attributes are the apsl flags
that are set by the extattr command. Audit
flags and file format attributes are not stored.
This support is only provided for archives using the USTAR format.
USTAR is the default format for
pax when
creating an archive. For
tar, the default
format is the original
tar format. The
-U option,
however, can be used to cause
tar to use
USTAR. When reading an archive,
tar will
automatically recognize the USTAR format– no special option
is required. (For more information about the USTAR format, see "tar
-- Format of tar archives" in
File formats.)
The
pax and
tar commands
also allow the storing/restoring of additional file attributes using
explicit options and environment variable. The following attributes
require special header support. OS390 format stores and restores these
by default. Examples of these additional attributes include:
- Links whose targets exceed 100 characters
- Access control lists (ACLs)
- File tag information
- Files with names longer than 255 characters
The extended USTAR support is provided by using two mechanisms:
encoding the information within the USTAR header record and through
the creation of special header files. (The same mechanism is used
for the OS390 archive format.)
Encoding information within the USTAR header record
External
link and extended attribute information is encoded within the standard
USTAR header in a manner which is compliant with POSIX standards and
should be tolerated by other non-z/OS versions
of pax and tar.
Because external links and extended attributes are specific to z/OS, however,
they cannot be restored on other platforms.
Special header files
Hard links and symbolic
links with targets greater than 100 characters cannot be preserved
within the standard USTAR format (for a hard link, the target is the
first occurrence of the hard link which is archived; subsequent hard
links refer to the first instance). In order to preserve links with
targets greater than 100 characters, special header files are
created for each link and stored in the archive. The special headers
are stored when one of the following is used: -o saveext option,
environment variable _OS390_USTAR=Y, or -x os390 option
(OS390 format).
Each special header file contains information
used by z/OS pax and tar to
restore the link to its original state. Special header files are
identified in the archive with type "S" (see "tar -- Format of tar
archives" in File formats for more information
about file types).
Each special header file in the archive
has the same name:
/tmp/OS390_USTAR_SUMMARY_timestamp
where
timestamp is the creation time (represented
in seconds since the epoch) of the first special header file. For
example:
/tmp/OS390_USTAR_SUMMARY_919026474
When
a special header file is required to preserve a file and the _OS390_USTAR=Y
environment variable was used, an informative message along with a
reason is displayed indicating that a special header file was created.
When -o saveext or -x os390 for pax or -UX or -S for tar is
used, the informational message is not displayed.
When reading
or listing an archive containing special header files and when using
the default extended USTAR support, pax and tar recognize
type "S" files as special header files and display or restore the
file described by the special header rather than the actual special
header file. So, typically, the presence of special header files
is not known to the user.
When the archive is complete, if
one or more special header files were created, then a final special
header summary file is created and added to the
archive. This file is identified in the archive with type "T" and
has the same name as the special header files. This file summarizes,
via script commands and comments, the contents of all previously archived
special header files. Its primary purpose is to provide help restoring
files included via special header files to those with versions of pax or tar that
do not implement extended USTAR support.
So, to allow users
of non-
z/OS systems
to read the
special header summary file, it is
encoded in the ASCII ISO8859-1 code set. To view the special header
file in EBCDIC code page IBM-1047, first convert the file using the
iconv command.
For example:
iconv -f ISO8859-1 -t IBM-1047 /tmp/OS390_USTAR_SUMMARY_919026474 >
summary_in _ebcdic
If extended USTAR support is
disabled during reading or listing an archive by using the pax
-o noext or the tar
-O option, or if the archive is processed by either
an earlier version of z/OS pax or tar that
does not implement extended USTAR support or a non-z/OS system version
of pax or tar,
then the special header files is not recognized and are processed
as unknown type regular files. During extraction, because all files
have the same name, each extracted special header file will overlay
the previous one with the special header summary file being the final
one restored.
For an example of the special header summary file,
see USTAR archive format.
File tags and the use of –o noext
Because
special headers are required to store file tag information, the storing
and restoring of file tag information is disabled if the user specifies
the –o noext option.
The –o noext option
is the default for writing an archive. To store information in the
special headers, the –o saveext or
_OS390_USTAR=Y environment variable must be used. When –o noext is
used, each file is treated as if it were untagged. That is, if –o noext is
specified, the stored or extracted file are set to untagged regardless
of its previous file tag setting.
–o noext disables
all attributes stored with special headers, so this option cannot
be used to selectively disable the storing or restoring of text flag
information. You will have to use chtag to
do that.
–o noext does
not affect the automatic conversion of files. If you use pax to
read, write or copy files, automatic conversion is disabled whether –o noext is
specified or not.
For more information about automatic conversion
and file tagging, see z/OS UNIX System Services Planning.
pax support for access control list (ACL)
- Archive writing or creating
- ACL data is stored in USTAR formatted archives using special headers
when one of the following is used: –o saveext option
or _OS390_USTAR=Y environment variable. OS390 format (-x os390 option)
automatically stores all special header information to include ACLs.
You
can use pax –o noext to
disable the creation of special headers. This prevents pax from
storing ACL data and other non-standard information such as file tag
data and long link names. However, there is no option to disable storing
of ACL data only.
- Archive reading or restoring
- By default, ACL data is not restored when reading or restoring
files from an archive. However, you can use pax –p
A to restore ACL data. You can also use pax
–p e (which restores all file attributes) to restore
ACL data.
- Archive copying
- If you need to preserve ACLs when copying files to an archive,
you must use pax –p A or pax
–p e.
- Archive listing (table of contents)
- For verbose output (pax –v), a + is
added to the end of the file permission bits for all files with extended
ACL entries. For more information about access control lists, see z/OS UNIX System Services Planning.
Examples
For archive listing (table
of contents):
If
file2 and
dir1 have extended
ACL entries:
> pax -vf acldata.pax
-rwx------ 1 STIERT SHUT 294912 Nov 9 09:57 file1
-rwx------+ 1 STIERT SHUT 294912 Nov 9 09:57 file2
drwxr-xr-x+ 2 STIERT SHUT 8192 Mar 20 2000 dir1/
Writing
(creating) an archive:
- The following creates an archive file named /tmp/files.pax from
all the files in the current working directory. The -v option
is used to display each file as it is being added:
pax -wvf /tmp/files.pax *
or
pax -wvf /tmp/files.pax .
The difference
between these two forms is that in the latter example (using .), names
recorded in the archive is preceded by a "./" which will include and
preserve the attributes of the current working directory and any hidden
files in the current working directory.
- Either of these commands creates a compressed version of the archive
created in Example 1:
pax -wzvf /tmp/files.pax.Z *
or
pax -wzvf /tmp/files.pax.Z .
In some instances, you can obtain a smaller, more compressed
output archive by first creating the pax archive uncompressed, and
then using the compress command on the archive.
For example:
pax -wvf /tmp/files.pax *
compress /tmp/files.pax
- The following example creates an archive /tmp/dironly.pax containing
only the files and directory names in the current directories (it
does not include the contents of subdirectories):
pax -wdvf /tmp/dironly.pax. *
- This example creates the archive /tmp/cfiles.pax containing
all c files in the current directory:
pax -wvf /tmp/cfiles.pax *.c
- This example creates the archive /tmp/allcfiles.pax containing
all c files in the current directory and all subdirectories:
pax -wvf /tmp/allcfiles.pax $(find . -name "*.c")
- This example creates the archive /tmp/ascii_src.pax using
all .c and .h files in the current directory converted into ASCII:
pax -wv -o to=ISO8859-1 -f /tmp/ascii_src.pax *.[ch]
- The following example creates the compressed archive /u/smith/oldfiles.pax.Z containing
all files on the system that were not accessed within the last 10
days:
pax -wvzf /u/smith/oldfiles.pax.Z $(find / -type f -atime +10)
- The following example creates the archive /tmp/basename.pax containing
all files in the directory sub1 stored in the archive with
"sub1/" removed from each component name. The pound character # is
used as the delimiter for the –s option:
pax -wv -s#sub1/## -f /tmp/basename.pax sub1/*
Reading an archive:
- This example extracts all the components of the archive source.pax.
The –v option is used to display
each file or directory as it is extracted.
pax -rvf source.pax
- To extract all files in source.pax and translate them from
ASCII to EBCDIC:
pax -ofrom=ISO8859-1,to=IBM-1047 -rf source.pax
- To extract all files in the archive source.pax ending with .h:
pax -rf source.pax `pax -f source.pax | grep h$`
This
example uses command substitution to first read the archive and generate
a list of all files in the archive that end with /.
- This example extracts files into a directory that is different
from the directory they are stored in within the archive. Assume the
names of all files stored in the archive source.pax begin with
the root directory (/). To extract them into /newroot/,
use the following command:
pax -rvf source.pax -s#/#/newroot/#
The –v option
is used to show the names of the files as they are extracted and is
not required.
- In the following examples, archive acldata.pax contains file1, file2,
and dir1. file1 has no ACL data, file2 has an
access ACL, and dir1 has a file default ACL, a directory default
ACL and an access ACL. If you only specify option –f,
your output is:
> pax -f acldata.pax
file1
file2
dir1
If you also specify –o A,
ACL information is displayed: > pax -o A -f acldata.pax
file1
file2
user:WELLIE2:rw-
group:SYS1:rwx
dir1
Finally, if you add the verbose
option, –v, you will see the file
permission bit settings that are associated with the file: > pax -o A -vf acldata.pax
-rwx------ 1 STIERT SHUT 294912 Nov 9 09:57 file1
-rwx------+ 1 STIERT SHUT 294912 Nov 9 09:57 file2
user:WELLIE2:rw-
group:SYS1:rwx
drwxr-xr-x+ 2 STIERT SHUT 8192 Mar 20 2000 dir1/
user:RRAND:rwx
user:WELLIE2:rw-
group:SHUT:rwx
fdefault:user:RRAND:rwx
fdefault:group:SHUT:r-x
default:user:ANGIEH:rwx
default:group:SYS1:r--
Specifying
pax -o A does
not automatically turn on the verbose table of contents format. You
must also specify
-v to display the file
permission bit settings associated with the file. To check if a file
has an ACL when for example,
file2 and
dir1 have ACLs:
>
pax -vf acldata.pax
-rwx------ 1 STIERT SHUT 294912 Nov 9 09:57 file1
-rwx------+ 1 STIERT SHUT 294912 Nov 9 09:57 file2
drwxr-xr-x+ 2 STIERT SHUT 8192 Mar 20 2000 dir1/
For
more information about access control lists, see z/OS UNIX System Services Planning.
To
store a file with an ACL using the OS390 archive format:
> pax -o os390 -wf acldata.pax fileAcls
Files
- /tmp/OS390_USTAR_SUMMARY_
- timestamp is a z/OS-extended
USTAR special header file. See z/OS-extended USTAR support for
more information.
Localization
pax uses
the following localization environment variables:
- LANG
- LC_ALL
- LC_COLLATE
- LC_CTYPE
- LC_MESSAGES
- LC_TIME
- LC_SYNTAX
- NLSPATH
See Localization for more
information.
Exit values
- 0
- Successful completion
- 1
- Failure due to any of the following reasons:
- Incorrect option
- Incorrect command-line arguments
- Out of memory
- Compression error
- Failure on extraction
- Failure on creation
If pax cannot extract
a particular file when reading, or find a particular file when writing,
it generates an error message and continues to process other files
but returns a status of 1. If any other error occurs, pax ends
immediately without attempting further processing.
If you see
the following message after a write operation:
If you want to go on, type device/filename when ready
it
indicates that your directory or device containing the archive file
is full. To continue, enter the name of a new directory; to end pax,
type <Ctrl-C>.
If you see that message after a read operation,
it means that pax could not find the archive
file that you specified, or that it was damaged. In this case, type <Ctrl-C>
to end the operation and then restart pax with
the correct archive name.
Portability
POSIX.2, X/Open Portability Guide.
The –L, –q, –V, –E, –p
x and –z options are
extensions of the POSIX standard.