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.
Note:
If the
pax archive is stored directly in a floppy disk block
special file
(e.g.
/dev/fd0), the archive overwrites the
first block of the disk, which the floppy driver,
devb-fdc, uses to store
media-type information that lets it dynamically adjust to diskettes
of differing media capacity being inserted in the drive (e.g.
720 KB vs 1.4 MB, 360 KB vs 1.2 MB etc.).
If the floppy driver can't determine the capacity, it assumes 1.4 MB.
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 the current directory to the floppy drive:
pax -w -f /dev/fd0 .
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.
On 16-bit architectures, including 16-bit versions of QNX 4., the
largest buffer size is 32K-1. This is due, in part, to using integers
in the buffer allocation schemes. On many of these machines, however, it
isn't possible to allocate blocks of memory larger than 32K.