PAX(1) BSD PAX(1)
NAME
pax - portable archive exchange
SYNOPSIS
pax [-Achimopuvy] [-f archive] [-s replstr] [-t device] [pattern...]
pax -r [-Achimnopuvy] [-f archive] [-s replstr] [-t device] [pattern...]
pax -w [-Aadhimuvy] [-b blocking] [-f archive] [-s replstr] [-t device]
[-x format] [pathname...]
pax -rw [-Ahilmopuvy] [-s replstr] [pathname...] directory
DESCRIPTION
pax reads and writes archive files which conform to the
Archive/Interchange File Format specified in IEEE Std. 1003.1-1988. pax
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 portability.
pax will also support traditional tar interfaces if invoked with the name
tar. See the tar(1) manual pages for more details.
pax and tar must be used with a mounted device. For example, when using
pax with /dev/rct8, first issue the command:
mt -f /dev/rct8 rewind
Then proceed with the pax command.
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 writes 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. 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.
-r pax 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 sames as those in the archive.
The supported archive formats are automatically detected on input.
The default output format is ustar, but may be overridden by the -x
format option described below.
-rw pax reads the files and directories named in the pathname operands
and copies 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
have the proper permissions before the copy can occur.
If neither the -r or -w options are given, then pax will list the
contents of the specified archive. In this mode, pax lists normal files
one per line, hard link pathnames as
pathname == linkname
and symbolic link pathnames (if supported by the implementation) as
pathname -> linkname
where pathname is the name of the file being extracted, and linkname is
the name of a file which appeared earlier in the archive.
If the -v option is specified, then pax list normal pathnames in the same
format used by the ls utility with the -l option. Hard links are shown
as
<ls -l listing> == linkname
and symbolic links (if supported) are shown as
<ls -l listing> -> linkname
pax is capable of reading and writing archives which span multiple
physical volumes. Upon detecting an end of medium on an archive which 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 Archive or extract Domain/OS-specific information, such as
extended ACLs.
-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 a m suffix multiplies blocking by 1048576 (1
megabyte). If not specified, blocking is automatically
determined on input and is ignored for -rw.
-c Complement the match sense of the the pattern operands.
-d Intermediate directories not explicitly listed in the archive are
not created. This option is ignored unless the -r option is
specified.
-f archive
The archive option specifies 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 (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 appropriate privileges to accomplish this.
-p Preserve the access time of the input files after they have been
copied.
-s replstr
File names are modified according to the substitution 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
here as an 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 occurs in the source string. Files that substitute 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 standard output when both -r and
-w are omitted, otherwise 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 specified in
Extended CPIO Format in IEEE Std. 1003.1-1988.
ustar The extended TAR interchange format specified 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 caused 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
pathnames if no pathname operands are specified. The format is one
pathname per line. Otherwise, the standard input is the archive file,
which is formatted according to one of the specifications in
Archive/Interchange File format in IEEE Std. 1003.1-1988, or some other
implementation-defined format.
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 format-reading
utility in Archive/Interchange File Format in IEEE Std. 1003.1-1988.)
The options -a, -c, -d, -i, -l, -p, -t, -u, and -y are provided for
functional compatibility with the historical 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
historical commands.
Operands
The following operands are available:
directory The destination directory pathname for copies when both the -r
and -w options are specified. The directory must exist and be
writable before the copy or and error results.
pathname A file whose contents are used instead of the files named on
the standard input. When a directory 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
find(1), tar(1), tar(5)
DIAGNOSTICS
pax will terminate immediately, without processing any additional 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.
WARNINGS
pax cannot copy some Domain/OS special typed files. pax or tar will
produce a message indicating that such files cannot be copied, and
continue. Some examples of such files are those of type org, passwd,
group, casehm, and mbx. When pax or tar attempts to archive a file of
one of these types, an error message such as: "ERROR!! Cannot archive
<filename>. It is of type <type>." is displayed. Therefore, it is wise
to not use pax or tar as a backup or installation tool because some
special Domain/OS typed files will not be recovered. One should use
omnibak, rbak or wbak to accomplish such a task.
BUGS
pax supports multiple volumes. However, you must mount each additional
volume before proceeding. Since the window from which you have issued the
pax command will be in a paused state (waiting for you to enter "go" or
"abort"), you must mount the tape device from another window, using the
mt command. For example, when using pax with /dev/rct8, issue the
command:
mt -f /dev/rct8 rewind
Then you can proceed to the paused window, and issue "go".
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 version of 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 restrictions on the length of pathnames 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 format does not keep link
count information.
COPYRIGHT
Copyright (c) 1989 Mark H. Colburn.
All rights reserved.
Redistribution and use in source and binary forms are permitted provided
that the above copyright notice is duplicated in all such forms and that
any documentation, advertising materials, and other materials related to
such distribution and use acknowledge that the software was developed by
Mark H. Colburn and sponsored by The USENIX Association.
THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
AUTHOR
Mark H. Colburn
NAPS International
117 Mackubin Street, Suite 1
St. Paul, MN 55102
mark@jhereg.MN.ORG
Sponsored by The USENIX Association for public distribution.