pax — Interchange portable archives

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.

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

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

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

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.

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

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

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

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

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.

pax uses the following environment variable:

_UNIX03

For more information about the effect of _UNIX03 on this command, see Shell commands changed for UNIX03.

pax uses the following localization environment variables:

• LANG
• LC_ALL
• LC_COLLATE
• LC_CTYPE
• LC_MESSAGES
• LC_TIME
• LC_SYNTAX
• NLSPATH

If you see the following message after a write operation:

If you want to go on, type device/filename when ready