pax(1) pax(1)
NAME
pax - portable archive processing
SYNOPSIS
pax [-cdnv] [-f archive] [-s instruction] ... [pattern ...]
pax -r[-cdiknuv] [-f archive] [-p string] ... [-s instruction] ...
[pattern ...]
pax -w[-dituvX] [-b blocksize] [-a] [-f archive] [-s instruction] ...
[-x format] [file ...]
pax -r -w[-diklntuvX] [-p string] ... [-s instruction] ... [file ...]
directory
DESCRIPTION
The pax command writes files to archive files, reads them or creates
lists of these files and copies directory hierarchies. A number of
archive formats are supported; see the -x format option.
The action executed depends on which of the -r and -w options are
specified. The four possible combinations of -r and -w give the four
operating modes: list mode, read mode, write mode, and copy mode, cor-
responding respectively to the four forms shown in the SYNOPSIS.
list In list mode (i.e. neither -r nor -w is specified), pax reads
an archive file from the standard input and writes the name of
the stored files, whose pathnames match the specified pattern,
to the standard output. If a specified file is a directory,
the file hierarchy rooted at that file will be written out
also.
read In read mode (i.e -r is specified, but not -w), pax reads an
archive file from the standard input and extracts the files
whose pathnames match the specified pattern. If the extracted
file is a directory, the file hierarchy rooted at that file is
also extracted. The extracted files are created relative to
the current directory.
The ownership, access and modification dates and times, as
well as file mode of the restored files are described in the
-p option.
Page 1 Reliant UNIX 5.44 Printed 11/98
pax(1) pax(1)
write In write mode (i.e. -w is specified, but not -r), pax writes
the contents of the file operands to the standard output in
archive format. If no file operand is specified, a list of
files to copy, one per line, is read from the standard input.
When specifying a directory, all files in the file hierarchy
rooted at that file are copied.
copy In copy mode (i.e. both -r and -w are specified), pax copies
the file operands to the destination directory directory.
If no file operands are specified, a list of all files to be
copied, one per line, is read from the standard input. When
specifying a directory, all files in the file hierarchy rooted
at that file are copied.
The copying process runs as if the copied files were written
to an archive file and subsequently extracted, except that
there may be hard links between the original and the copied
files.
If temporary directories are needed to extract a file in read or copy
mode, these are created by pax.
At least one file must match the specified pattern or file operands,
otherwise pax writes a diagnostic message to the standard message out-
put for each operand that is unmatched, and terminates with a non-zero
exit status.
The archive formats supported are automatically recognized when read-
ing the file. The standard output format for archives when writing (no
-x option specified) is the extended tar format.
An archive can span multiple files. The pax command determines what
file to read or write as the next file.
If the selected archive format supports the specification of links
between files, pax returns an error if no link can be created between
these files during extraction.
Page 2 Reliant UNIX 5.44 Printed 11/98
pax(1) pax(1)
OPTIONS
-r Reads an archive file from the standard input.
-w Writes files in the specified archive format to the standard
input.
-a Appends files to the end of the archive.
-b blocksize
Puts the data in blocks in the archive file, and specifies the
block size as a positive decimal integer. Devices and archive
formats may impose restrictions on blocking. Blocking is automat-
ically determined on input. Default blocking during the creation
of archives depends on the archive format (see the -x option
below). To maintain a portable archive, the block size may not be
bigger than 32 KB.
-c Selects all files apart from those specified by the pattern or
file operands.
-d The file hierarchy rooted at this file in a directory is not
copied, read, or archived.
-f archive
Specifies the pathname of the input archive (in list or read
mode) or the output archive (write mode). This archive is used
instead of the standard input or output.
-i Renames files interactively. For every file archived whose name
matches the pattern operand, or for every file that matches a
file operand, a prompt is written to /dev/tty. This prompt con-
tains the name of the file. A line is read from /dev/tty. If this
line is blank, the file is skipped. If the line consists of a
single period, the file is processed without the name being modi-
fied. Otherwise the name is replaced by the contents of the line.
If an end-of-line character is found when reading a response, or
if /dev/tty cannot be opened for reading or writing, the pax com-
mand terminates immediately with a non-zero exit status.
-k Prevents the overwriting of existing files.
-l Creates links between files. Hard links are created whenever pos-
sible between source and target file hierarchies.
Page 3 Reliant UNIX 5.44 Printed 11/98
pax(1) pax(1)
-n Selects the first file archived that matches the pattern operand.
Only one matching file is selected for every pattern operand
(file hierarchies rooted at the directories are not affected by
this restriction).
-p string
Determines file characteristics (privileges). The string argument
contains the file characteristics that must be retained or
ignored during extraction. The string consists of the a, e, m, o
and p specification characters. Several characters can be con-
catenated in the same string, and the -p option can be specified
more than once. The specification characters mean the following:
a Date and time of the last file access are set to the current
date.
e User ID, group ID, access permissions (see chmod), date and
time of the last access and modification are preserved.
m Date and time of the last file modification are not
preserved.
o User ID and group ID are preserved.
p Access rights are preserved.
In the list above, "preserved" means that an attribute saved in
the archive will be assigned to the extracted file, depending on
the privileges of the invoking process. Otherwise, the attribute
is defined as part of the normal file creation action.
pax does not set the s bits for the file mode if neither e nor o
are specified, or the user and group IDs preserved.
If for any reason, one of these attributes cannot be preserved,
pax writes a diagnostic message to the standard output. If an
attribute cannot be preserved, the extracted file is not deleted,
although it does effect the exit status.
If specification characters are duplicated in the string argument
or are in conflict with the other arguments, the last argument
entered has priority. If for example -p eme is specified, the
date and time of the last file modification are preserved.
-s instruction
Modifies files specified by the pattern or file operands, accord-
ing to the instruction. The syntax of ed is used for this. The
concepts "address" and "line" mean nothing in the context of the
pax command. The following format is used:
-s /old/new/[gp]
Page 4 Reliant UNIX 5.44 Printed 11/98
pax(1) pax(1)
As in ed, old is a simple regular expression and new can contain
& signs, \n (where n is a number), references, and subexpres-
sions. The old string can also contain a newline character.
All characters can be used as delimiters (e.g. /). A number of -s
expressions are allowed. The expressions are evaluated in the
specified order ending with the first successful substitution.
The optional trailing g is as defined in ed. The optional trail-
ing p writes successful substitutions to the standard error out-
put. Filenames replaced by a null string are ignored when reading
and writing archives.
-t The date and time of the last access to archived files are set to
the value they had before being accessed by pax.
-u Ignores files that are an older version (with an older last
modification date/time) of a file of the same name that already
exists. In read mode, an archived file that has the same name as
a file in the file system is extracted if the archived file is
more current than the one in the file system. A file is only
saved in write mode if there is no more recent version with the
same name.
Note: pax -wu behaves in the same manner as -wau, i.e. files are
appended to the end of the archive.
In copy mode, a file in the target hierarchy is replaced by a
file in the source hierarchy by a link to the file in the source
hierarchy, if it is the more current.
-v In list mode, a detailed table of contents is written to the
standard output. Otherwise the pathnames of the stored file are
written to the standard output.
Page 5 Reliant UNIX 5.44 Printed 11/98
pax(1) pax(1)
-x format
Specifies the archive output format. pax recognizes the following
formats:
cpio The extended cpio interchange format. The default block
size for this character-oriented archive file format is
5120. Implementations of pax support all values for the
block size up to 32256 that are a multiple of 512.
Note: pax only displays transportable cpio archives.
These are generated with cpio -o -H odc.
ustar The extended tar interchange format. The default block
size for this character-oriented archive file format is
10240. Implementations of pax support all values for the
block size up to 32256 that are a multiple of 512.
Note: You must use this format for files larger than
2 GB. A warning is issued in this case.
pax terminates immediately with a non-zero exit status if an
attempt is made to append data to an archive file in a different
format than the existing archive format.
-X pax will not switch to a directory in a different file system
when traversing a file hierarchy specified by a pathname.
The options that operate on the names of files (-c, -i, -n, -s, -u and
-v) are evaluated one after the other as described below:
In write mode, the files are selected according to pathnames specified
by the user, and the modifications performed using the -n and -u
options. The -s and -i options then modify the names of the selected
files. The -v option outputs the names resulting from these modifica-
tions.
If both the -u option and the -n option are specified, px does not
consider a file unless it is more current than the file to which it is
compared.
directory Pathname of the target directory for copy mode.
file Pathname of the file to be copied or archived.
pattern A pattern that matches one or more pathnames of archived
files. By default (if no pattern is specified), all files in
the archive are selected.
Page 6 Reliant UNIX 5.44 Printed 11/98
pax(1) pax(1)
STDIN
In write mode, the standard input is only used if no file operands are
specified. The standard output must then be a text file containing a
list of the pathnames. The file must contain one pathname per line,
and there may be no preceding or trailing blank characters.
In list and read mode, the standard input must be an archive file.
Otherwise the standard input is not used.
INPUT FILES
The input file specified by archive or the standard input if the
archive is read from it, is a file formatted according to one of the
archive formats listed in the -x option.
Prompts are written and responses read to or from /dev/tty.
ENVIRONMENT VARIABLES
LANG Specifies a default value for the locale variables that are
unset or null. If LANG is unset or null, the corresponding
default value of the locale is used. If the locale variable
contains an invalid setting, pax behaves as if no variable
were set.
LCALL If this variable has a value, i.e. is not empty, this value
overwrites the values of all other locale variables.
LCCOLLATE
Determines the locale for the behavior of ranges, equivalence
classes and collating elements used in the pattern matching
expressions for the pattern operand, in the simple regular
expression for the -s option, and in the extended regular
expression defined for the yesexpr locale keyword in the
LCMESSAGES category.
LCCTYPE Determines the locale for the interpretation of byte
sequences (e.g. single-byte as opposed to multibyte charac-
ters in arguments and input files), for the behavior of char-
acter classes used in the extended regular expressions
defined for the yesexpr locale keyword in the LCMESSAGES
category, and for pattern matching.
LCMESSAGES
Determines the locale for the processing of yes/no responses,
as well as the format and language of diagnostic messages,
output by pax.
LCTIME Determines the format and the content of date and time speci-
fications if the -v option is specified.
NLSPATH Determines the position of the message catalog for the pro-
cessing of LCMESSAGES.
Page 7 Reliant UNIX 5.44 Printed 11/98
pax(1) pax(1)
STDOUT
If -f is not specified in write mode, the standard output is the
archive formatted according to one of the archive formats listed in
the -x option.
In list mode, the table of contents of the selected files are written
to the standard output in the following format:
"%s\n", pathname
If -v is specified in list mode, the table of contents of the selected
files is written to the standard output in the following format:
Pathnames that represent hard links to previous files are written in
this format:
"%s == %s\n", ls-llisting, linkname
All other pathnames are written in this format:
"%s\n", ls-llisting
ls-llisting is the format created by the ls command with the -l
option.
STDERR
If -v is specified in read, write or copy mode, pax writes the path-
names it processes to the standard error output in the following for-
mat:
"%s\n", pathname
These pathnames are output at the start of file processing. The final
newline character is output after the file is read or written.
If the -s option is specified, and there is a trailing p in the sub-
stitution string, substitutions are written to the standard error out-
put in the following format:
"%s >> %s\n", originalpathname, newpathname
Any messages about the archive format are also written to the standard
error output.
OUTPUT FILES
In read mode, the files extracted or copied are of the archived file
type.
In write mode, the output file named by the -f option is a file for-
matted according to archive formats listed in the -x option.
Page 8 Reliant UNIX 5.44 Printed 11/98
pax(1) pax(1)
EXIT STATUS
0 All files were successfully processed.
>0 An error occurred.
CONSEQUENCE OF ERRORS
If pax cannot create a file or a link when reading an archive, cannot
find a file when writing an archive, or cannot preserve the user ID,
group ID, or access rights with the -p option set, a diagnostic mes-
sage is written to the standard error output and a non-zero exit
status is returned. Processing is continued nonetheless. If pax cannot
create a link to a file, by default it does not create a second copy
of the file.
If the extraction of a file from an archive is prematurely ended by a
signal or an error, pax may only have extracted a part of the file, or
(if the -n option is not specified) a file under the name specified by
the user, that is not the file the user wanted.
Extracted directory access rights may also have additional bits from
the file-creation mode mask as well as incorrect information about the
date and time of the last file access and modification.
APPLICATION USAGE
The -p option was introduced to reconcile differences between the con-
ventional tar and cpio implementations. In particular these two com-
mands use -m in very different ways. The -p option also provides
extended facilities for the consistent addressing of future file
attributes, e.g. for extended security systems or high performance
archives. Of the many combinations, only two modes are usually used:
-p e "Preserve everything" is used by the conventional superuser
with all the appropriate privileges to preserve all file attri-
butes as they are recorded in the archive. The e flag is the
sum of o and p.
-p p "Preserve" the access rights. This is used by users with regu-
lar privileges who would like to preserve all file attributes
apart from the owner. The file date and time specifications are
preserved by default. However this can be deactivated with two
other flags, and the date and time of extraction used.
Some of the functionalities described require appropriate privileges
for whoever calls pax, particularly when creating block-oriented or
character-oriented special files, when restoring the date and time of
file access (-t option), provided that the user is not the owner of
the file, or when preserving the group, and the mode (-p option).
MESSAGES
Warning: just archiving file >2GB.
Unable to handle file >2GB with "-x cpio" option.
Page 9 Reliant UNIX 5.44 Printed 11/98
pax(1) pax(1)
EXAMPLES
The following command writes all files as well as the contents of
directories whose names begin with "g" to the archive file.pax (pack):
pax -wv -f file.pax g*
The following command reads the archive file.pax (unpack):
pax -rv -f file.pax
The following command copies the contents of the current directory to
a tape:
pax -w -f /dev/rmt/m0 .
The following commands copy the olddir file hierarchy to newdir:
mkdir newdir
pax -rw olddir newdir
The following command reads the a.pax archive, whereby all file direc-
tories/files rooted in /usr in the archive relative to the current
directory are extracted.
pax -r -s ',//*usr//*,,' -f a.pax
SEE ALSO
cpio(1), tar(1).
Page 10 Reliant UNIX 5.44 Printed 11/98