Portable archive interchange (POSIX)
Syntax:
List archive contents:
pax [-cimopuvy] [-f archive] [-s replstr]...
[-t device] [pattern...]
Read an archive:
pax -r [-cimnopuvy] [-f archive] [-s replstr]...
[-t device] [pattern...]
Write an archive:
pax -w [-dimuvy] [-b blocking] [-[a]f archive]
[-s replstr]... [-t device] [-x format]
[pathname...]
Copy files:
pax -rw [-ilmopuvy] [-s replstr]... [pathname...]
directory
Runs on:
QNX Neutrino, Microsoft Windows
Options:
- -a
- Append the files specified by pathname to the archive specified with -f.
- -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 automatically determined on input and is ignored for
-rw (copy files).
- -c
- Complement the match sense of the pattern operands.
- -d
- Don't create intermediate directories not explicitly listed in the archive.
This option is applied only if you specify the -r option.
- -f archive
- Use archive as the pathname of the input or output
archive, overriding the default of standard input for -r
or standard output for -w.
- -i
- Interactively rename files. Substitutions specified by -s
options are performed before requesting the new filename from you.
If you enter an empty line, the file is skipped.
If EOF is encountered, pax exits with an exit status of 0.
- -l
- (el) When possible, link rather than copy files.
- -m
- Don't keep file modification times.
- -n
- When you specify -r, but not -w,
treat the pattern operands as ordinary
filenames. Only the first occurrence of each of these files in the input
archive is read. The pax utility exits with an exit status of
0 after all files in the list have been read.
If it can't find one or more of the files in the list,
pax writes a diagnostic
to standard error for each of these files and exits with a nonzero
exit status. The filenames 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 appropriate privileges to accomplish this.
- -p
- Preserve the access time of the input files after they have been copied.
- -s replstr
- Modify filenames according to the substitution expression. The syntax for
the expression is:
-s /old/new/[gp]
You can use any non-null character as a delimiter (a /
is used here as an example). Multiple -s 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 occurs in the source string.
If a filename becomes an empty string after applying substitutions to it, it's ignored both on input and output.
- -t device
- The device argument 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 preexisting file with the same name.
- -v
- Be verbose; list filenames as they're encountered. This option produces
a table of contents listing on the standard output when both
-r and -w are omitted; otherwise
the filenames are printed to standard error as they are encountered in the archive.
- -x format
- Use this output archive format.
The input format is automatically determined when you use the -r option.
The supported formats are:
- cpio
- The extended cpio interchange format specified in
POSIX Std 1003.1-1988.
- ustar
- The extended tar interchange format, also specified in
POSIX 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 you're prompted for the disposition. EOF or an input
line starting with the character q causes pax
to exit. Otherwise, an input line starting with anything other than
y causes the file to be ignored. You can't use this option
in conjunction with the -i option.
Note:
Only the last -f or -t option takes effect.
- directory
- The destination directory pathname for copies when both the
-r and -w options are specified. The
directory must exist and you must have the appropriate write permissions, or an error results.
- pathname
- A file to be copied or a directory containing files and subdirectories to be (recursively) copied in addition to
the directory itself.
- pattern
- A pattern given in the standard shell pattern-matching notation.
If no pattern is specified, the default is *, which selects all files.
Modes of operation:
If you don't specify -r or -w, then
pax lists the contents of the specified archive. In this mode,
pax lists normal files one per line. Hard link pathnames are listed as:
pathname == linkname
where pathname is the name of the file being extracted,
and linkname is the name of a file that appeared earlier in the archive.
Symbolic link pathnames are listed as:
pathname -> destination_path
If you specify -v, then pax lists normal pathnames in the same format used by the
ls
utility with the -l (el) option, except for hard links, which are shown as:
<ls -l listing> == linkname
The modes of operation related to combinations of -r and -w are as follows:
- -r
- Read an archive file from the standard input; select for extraction only
those files whose names match any of the pattern
operands. The selected files are conditionally created and copied
relative to the current directory tree, subject to the options chosen.
By default, the owner and group of selected files are those of
the invoking process, and the permissions and modification times are the same as those in the archive.
The supported archive formats are automatically detected on input.
- -w
- Write the files and directories specified by
pathname operands to the standard output, together
with the pathname and status information prescribed by the archive format
used. The default output format is tar, but you can
override this by using the -x format option described below.
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 pathnames to copy, one pathname per
line. In this case, only those pathnames appearing on the standard input are copied.
- -rw
- Read the files and directories named in the pathname
operands and copy them to the destination 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 pathnames to copy, one pathname per line. In this
case, only those pathnames appearing on the standard input are copied.
The directory named by the directory operand must exist and must have
the proper permissions before the copy can occur.
Description:
The pax utility reads and writes archive files that conform
to the archive/interchange file format specified in POSIX Std
1003.1-1988. The utility can also read, but not write, a number of
other file formats. 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 portability.
The pax utility also supports traditional cpio
and System V tar interfaces if invoked with those names (they're links to pax).
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 isn't yet completed, pax prompts
you for the next volume of the archive and lets you specify the location of the next volume.
Combinations of the -r and -w command-line
arguments specify whether pax reads, writes, or lists
the contents of the specified archive, or moves the specified files to another directory.
When writing to an archive, the standard input is used as a list of
pathnames if no pathname operands are specified. The
format is one pathname per line. When reading, the standard input is the archive
file, which is formatted according to one of the format specifications in POSIX Std 1003.1-1988.
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.
(See Archive/Interchange File Format in POSIX Std 1003.1-1988.)
Note that the options -a, -c,
-d, -i, -l,
-p, -t,
and -y are provided for functional compatibility
with the historical cpio and tar utilities.
The option defaults were chosen based on the most common usage of
these options, so some of the options have meanings different from
those of the historical commands.
Examples:
Copy the contents of olddir to newdir:
mkdir newdir
cd olddir
pax -rw . ../newdir
Read the archive pax.out with all files rooted in /usr
in the archive extracted relative to the current directory (note the
use of commas as pattern separators for the -s option):
pax -r -s ",^/usr/,," -f pax.out
Files:
The controlling terminal (/dev/tty) is used to prompt
the user for information when the -i or -y options are specified.
Exit status:
- 0
- All files in the archive were processed successfully.
- >0
- The pax utility aborted due to errors encountered during operation.
Caveats:
Special permissions may be required to copy or extract special 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 and tar.
The archive formats described in Archive/Interchange File Format have certain restrictions
that have been carried over from historical usage. For example, pathnames stored in the
archive can be no more than 255 characters in length.
When getting an ls -l style listing on tar
format archives, link counts are listed as zero since the ustar
archive format doesn't keep link count information.