pax(1P) INTERACTIVE UNIX System (POSIX) pax(1P)
NAME
pax - portable archive exchange
SYNOPSIS
pax [-cimopuvy] [-f archive] [-s replstr] [-t device] [pat-
tern...]
pax -r [-cimnopuvy] [-f archive] [-s replstr] [-t device]
[pattern...]
pax -w [-adimuvy] [-b blocking] [-f archive] [-s replstr]
[-t device] [-x format] [pathname...]
pax -rw [-ilmopuvy] [-s replstr] [pathname...] directory
DESCRIPTION
The pax utility reads and writes archive files that conform
to the ``Archive/Interchange File Format'' specified in IEEE
Std. 1003.1-1988. The pax utility can also read, but not
write, a number of other file formats in addition to those
specified in the ``Archive/Interchange File Format''
description. Support for these traditional file formats,
such as V7 tar and System V binary cpio format archives, is
provided for backward compatibility and to maximize porta-
bility.
Combinations of the -r and -w command line arguments specify
whether pax will read, write, or list the contents of the
specified archive, or move the specified files to another
directory.
The command line arguments are:
-w This argument writes the files and directories speci-
fied by pathname operands to the standard output
together with the path name and status information
prescribed by the archive format used. A directory
pathname operand refers to the files and (recursively)
subdirectories of that directory. If no pathname
operands are given, then the standard input is read to
get a list of path names to copy, one path name per
line. In this case, only those path names appearing on
the standard input are copied.
-r The pax utility reads an archive file from the standard
input. Only files with names that match any of the
pattern operands are selected for extraction. The
selected files are conditionally created and copied
relative to the current directory tree, subject to the
options described below. By default, the owner and
group of selected files will be that of the invoking
process, and the permissions and modification times
will be the same as those in the archive.
Rev. 1.2 Page 1
pax(1P) INTERACTIVE UNIX System (POSIX) pax(1P)
The supported archive formats are automatically
detected on input. The default output format is ustar,
but that may be overridden by the -x format option
described below.
-rw The pax utility reads the files and directories named
in the pathname operands and copies them to the desti-
nation directory. A directory pathname operand refers
to the files and (recursively) subdirectories of that
directory. If no pathname operands are given, the
standard input is read to get a list of path names to
copy, one path name per line. In this case, only those
path names appearing on the standard input are copied.
The directory named by the directory operand must exist
and it must have the proper permissions before the copy
can occur.
If neither the -r or -w options are given, pax will list the
contents of the specified archive. In this mode, pax lists
normal files one per line, showing link path names as:
pathname == linkname
If the -v option is specified, then pax lists normal path
names in the same format used by the ls utility with the -l
option. Links are shown as:
<ls -l listing> == linkname
The pax utility is capable of reading and writing archives
that span multiple physical volumes. Upon detecting an end
of medium on an archive that is not yet completed, pax will
prompt the user for the next volume of the archive and will
allow the user to specify the location of the next volume.
Options
The following options are available:
-a The files specified by pathname are appended to
the specified archive.
-b blocking
Block the output at blocking bytes per write to
the archive file. A k suffix multiplies blocking
by 1024, a b suffix multiplies blocking by 512,
and an m suffix multiplies blocking by 1048576 (1
megabyte). If not specified, blocking is automat-
ically determined on input and is ignored for -rw.
-c Complement the match sense of the pattern
operands.
-d Intermediate directories not explicitly listed in
Rev. 1.2 Page 2
pax(1P) INTERACTIVE UNIX System (POSIX) pax(1P)
the archive are not created. This option is
ignored unless the -r option is specified.
-f archive
The archive option specifies the path name of the
input or output archive, overriding the default of
standard input for -r or standard output for -w.
-i Interactively rename files. Substitutions speci-
fied by -s options (described below) are performed
before requesting the new file name from the user.
A file is skipped if an empty line is entered, and
pax exits with an exit status of 0 if EOF is
encountered.
-l Files are linked rather than copied when possible.
-m File modification times are not retained.
-n When -r is specified, but -w is not, the pattern
arguments are treated as ordinary file names.
Only the first occurrence of each of these files
in the input archive is read. The pax utility
exits with a zero exit status after all files in
the list have been read. If one or more files in
the list is not found, pax writes a diagnostic to
standard error for each of the files and exits
with a non-zero exit status. The file names are
compared before any of the -i, -s, or -y options
are applied.
-o Restore file ownership as specified in the
archive. The invoking process must have appropri-
ate privileges to accomplish this.
-p Preserve the access time of the input files after
they have been copied.
-s replstr
Filenames are modified according to the substitu-
tion expression using the syntax of ed(1) as
shown:
-s /old/new/[gp]
Any non-null character may be used as a delimiter
(a / is used in this example). Multiple -s
expressions may be specified; the expressions are
applied in the order specified terminating with
the first successful substitution. The optional
trailing p causes successful mappings to be listed
on standard error. The optional trailing g causes
the old expression to be replaced each time it
Rev. 1.2 Page 3
pax(1P) INTERACTIVE UNIX System (POSIX) pax(1P)
occurs in the source string. Files that substi-
tute to an empty string are ignored both on input
and output.
-t device The device option argument is an implementation-
defined identifier that names the input or output
archive device, overriding the default of standard
input for -r and standard output for -w.
-u Copy each file only if it is newer than a pre-
existing file with the same name. This implies
-a.
-v List file names as they are encountered. Produces
a verbose table of contents listing on the stan-
dard output when both -r and -w are omitted; oth-
erwise the file names are printed to standard
error as they are encountered in the archive.
-x format Specifies the output archive format. The input
format, which must be one of the following, is
automatically determined when the -r option is
used. The supported formats are:
cpio The extended CPIO interchange format speci-
fied in ``Extended CPIO Format'' in IEEE
Std. 1003.1-1988.
ustar The extended TAR interchange format speci-
fied in ``Extended TAR Format'' in IEEE
Std. 1003.1-1988. This is the default
archive format.
-y Interactively prompt for the disposition of each
file. Substitutions specified by -s options
(described above) are performed before prompting
the user for disposition. EOF or an input line
starting with the character q cause pax to exit.
Otherwise, an input line starting with anything
other than y causes the file to be ignored. This
option cannot be used in conjunction with the -i
option.
Only the last of multiple -f or -t options take effect.
When writing to an archive, the standard input is used as a
list of path names if no pathname operands are specified.
The format is one path name per line. Otherwise, the stan-
dard input is the archive file.
The user ID and group ID of the process, together with the
appropriate privileges, affect the ability of pax to restore
ownership and permissions attributes of the archived files.
Rev. 1.2 Page 4
pax(1P) INTERACTIVE UNIX System (POSIX) pax(1P)
The options -a, -c, -d, -i, -l, -p, -t, -u, and -y are pro-
vided for functional compatibility with the historical cpio
and tar utilities. The option defaults were chosen based on
the most common usage of these options; therefore, some of
the options have meanings different than those of the his-
torical commands.
Operands
The following operands are available:
directory The destination directory path name for copies
when both the -r and -w options are specified.
The directory must exist and be writable before
the copy or error results.
pathname A file whose contents are used instead of the
files named on the standard input. When a direc-
tory is named, all of its files and (recursively)
subdirectories are copied as well.
pattern A pattern is given in the standard shell pattern
matching notation. The default if no pattern is
specified is *, which selects all files.
EXAMPLES
The following command:
pax -w -f /dev/rmt0 .
copies the contents of the current directory to tape drive
0.
The commands
mkdir newdir
cd olddir
pax -rw . ../newdir
copies the contents of olddir to newdir.
The command
pax -r -s ',//*usr//*,,' -f pax.out
reads the archive pax.out with all files rooted in /usr in
the archive extracted relative to the current directory.
FILES
/dev/tty Used to prompt the user for information when the
-i or -y options are specified
SEE ALSO
cpio(1), find(1), tar(1).
Rev. 1.2 Page 5
pax(1P) INTERACTIVE UNIX System (POSIX) pax(1P)
cpio(5), tar(5) in the INTERACTIVE SDS Guide and
Programmer's Reference Manual.
DIAGNOSTICS
pax will terminate immediately, without processing any addi-
tional files on the command line or in the archive.
EXIT CODES
pax will exit with one of the following values:
0 All files in the archive were processed successfully.
>0 pax aborted due to errors encountered during operation.
BUGS
Special permissions may be required to copy or extract spe-
cial files.
Device, user ID, and group ID numbers larger than 65535
cause additional header records to be output. These records
are ignored by some historical versions of cpio(1) and
tar(1).
The archive formats described in ``Archive/Interchange File
Format'' have certain restrictions that have been carried
over from historical usage. For example, there are restric-
tions on the length of path names stored in the archive.
When getting an ls -l style listing on tar format archives,
link counts are listed as zero since the ustar archive for-
mat does not keep link count information.
SOURCE
Copyright © 1989 Mark H. Colburn.
All rights reserved.
This version of the pax utility is derived from software
developed by Mark H. Colburn and sponsored by The USENIX
Association.
ADDED VALUE
This entry, supplied by INTERACTIVE Systems Corporation, is
an extension of UNIX System V.
Rev. 1.2 Page 6