pax.1

早期freebsd实现

.\" Copyright (c) 1992 Keith Muller.
.\" Copyright (c) 1992, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Keith Muller of the University of California, San Diego.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)pax.1	8.4 (Berkeley) 4/18/94
.\"
.Dd April 18, 1994
.Dt PAX 1
.Os BSD 4.4
.Sh NAME
.Nm pax
.Nd read and write file archives and copy directory hierarchies
.Sh SYNOPSIS
.Nm pax
.Op Fl cdnv
.Bk -words
.Op Fl f Ar archive
.Ek
.Bk -words
.Op Fl s Ar replstr
.Ar ...
.Ek
.Bk -words
.Op Fl U Ar user
.Ar ...
.Ek
.Bk -words
.Op Fl G Ar group
.Ar ...
.Ek
.Bk -words
.Oo
.Fl T
.Op Ar from_date
.Op Ar ,to_date
.Oc
.Ar ...
.Ek
.Op Ar pattern ...
.Nm pax
.Fl r
.Op Fl cdiknuvDYZ
.Bk -words
.Op Fl f Ar archive
.Ek
.Bk -words
.Op Fl o Ar options
.Ar ...
.Ek
.Bk -words
.Op Fl p Ar string
.Ar ...
.Ek
.Bk -words
.Op Fl s Ar replstr
.Ar ...
.Ek
.Op Fl E Ar limit
.Bk -words
.Op Fl U Ar user
.Ar ...
.Ek
.Bk -words
.Op Fl G Ar group
.Ar ...
.Ek
.Bk -words
.Oo
.Fl T
.Op Ar from_date
.Op Ar ,to_date
.Oc
.Ar ...
.Ek
.Op Ar pattern ...
.Nm pax
.Fl w
.Op Fl dituvHLPX
.Bk -words
.Op Fl b Ar blocksize
.Ek
.Oo
.Op Fl a
.Op Fl f Ar archive
.Oc
.Bk -words
.Op Fl x Ar format
.Ek
.Bk -words
.Op Fl s Ar replstr
.Ar ...
.Ek
.Bk -words
.Op Fl o Ar options
.Ar ...
.Ek
.Bk -words
.Op Fl U Ar user
.Ar ...
.Ek
.Bk -words
.Op Fl G Ar group
.Ar ...
.Ek
.Bk -words
.Op Fl B Ar bytes
.Ek
.Bk -words
.Oo
.Fl T
.Op Ar from_date
.Op Ar ,to_date
.Op Ar /[c][m]
.Oc
.Ar ...
.Ek
.Op Ar file ...
.Nm pax
.Fl r
.Fl w
.Op Fl diklntuvDHLPXYZ
.Bk -words
.Op Fl p Ar string
.Ar ...
.Ek
.Bk -words
.Op Fl s Ar replstr
.Ar ...
.Ek
.Bk -words
.Op Fl U Ar user
.Ar ...
.Ek
.Bk -words
.Op Fl G Ar group
.Ar ...
.Ek
.Bk -words
.Oo
.Fl T
.Op Ar from_date
.Op Ar ,to_date
.Op Ar /[c][m]
.Oc
.Ar ...
.Ek
.Op Ar file ...
.Ar directory
.Sh DESCRIPTION
.Nm Pax
will read, write, and list the members of an archive file,
and will copy directory hierarchies.
.Nm Pax 
operation is independent of the specific archive format,
and supports a wide variety of different archive formats.
A list of supported archive formats can be found under the description of the
.Fl x
option.
.Pp
The presence of the
.Fl r
and the
.Fl w
options specifies which of the following functional modes
.Nm pax
will operate under:
.Em list , read , write ,
and
.Em copy.
.Bl -tag -width 6n
.It <none>
.Em List .
.Nm Pax
will write to
.Dv standard output
a table of contents of the members of the archive file read from
.Dv standard input ,
whose pathnames match the specified
.Ar patterns.
The table of contents contains one filename per line
and is written using single line buffering.
.It Fl r
.Em Read .
.Nm Pax
extracts the members of the archive file read from the
.Dv standard input ,
with pathnames matching the specified 
.Ar patterns.
The archive format and blocking is automatically determined on input.
When an extracted file is a directory, the entire file hierarchy
rooted at that directory is extracted.
All extracted files are created relative to the current file hierarchy.
The setting of ownership, access and modification times, and file mode of
the extracted files are discussed in more detail under the
.Fl p
option.
.It Fl w
.Em Write .
.Nm Pax
writes an archive containing the 
.Ar file
operands to
.Dv standard output
using the specified archive format.
When no 
.Ar file
operands are specified, a list of files to copy with one per line is read from 
.Dv standard input .
When a 
.Ar file
operand is also a directory, the entire file hierarchy rooted
at that directory will be included.
.It Fl r Fl w
.Em Copy .
.Nm Pax
copies the
.Ar file
operands to the destination
.Ar directory .
When no 
.Ar file
operands are specified, a list of files to copy with one per line is read from
the
.Dv standard input .
When a
.Ar file
operand is also a directory the entire file
hierarchy rooted at that directory will be included.
The effect of the
.Em copy
is as if the copied files were written to an archive file and then
subsequently extracted, except that there may be hard links between
the original and the copied files (see the
.Fl l
option below).
.Pp
.Em Warning :
The destination
.Ar directory
must not be one of the
.Ar file
operands or a member of a file hierarchy rooted at one of the
.Ar file
operands.
The result of a
.Em copy
under these conditions is unpredictable.
.El
.Pp
While processing a damaged archive during a
.Em read
or
.Em list
operation,
.Nm pax
will attempt to recover from media defects and will search through the archive
to locate and process the largest number of archive members possible (see the
.Fl E
option for more details on error handling).
.Sh OPERANDS
.Pp
The
.Ar directory
operand specifies a destination directory pathname.
If the
.Ar directory
operand does not exist, or it is not writable by the user,
or it is not of type directory,
.Nm Pax
will exit with a non-zero exit status.
.Pp
The
.Ar pattern
operand is used to select one or more pathnames of archive members.
Archive members are selected using the pattern matching notation described
by
.Xr fnmatch 3 .
When the 
.Ar pattern
operand is not supplied, all members of the archive will be selected.
When a 
.Ar pattern
matches a directory, the entire file hierarchy rooted at that directory will
be selected.
When a
.Ar pattern
operand does not select at least one archive member,
.Nm pax
will write these
.Ar pattern
operands in a diagnostic message to
.Dv standard error
and then exit with a non-zero exit status.
.Pp
The
.Ar file
operand specifies the pathname of a file to be copied or archived.
When a
.Ar file
operand does not select at least one archive member,
.Nm pax
will write these
.Ar file
operand pathnames in a diagnostic message to
.Dv standard error
and then exit with a non-zero exit status.
.Sh OPTIONS
.Pp
The following options are supported:
.Bl -tag -width 4n
.It Fl r
Read an archive file from
.Dv standard input
and extract the specified
.Ar files .
If any intermediate directories are needed in order to extract an archive
member, these directories will be created as if
.Xr mkdir 2
was called with the bitwise inclusive
.Dv OR 
of
.Dv S_IRWXU , S_IRWXG ,
and
.Dv S_IRWXO 
as the mode argument.
When the selected archive format supports the specification of linked
files and these files cannot be linked while the archive is being extracted,
.Nm pax
will write a diagnostic message to
.Dv standard error
and exit with a non-zero exit status at the completion of operation.
.It Fl w
Write files to the
.Dv standard output
in the specified archive format.
When no
.Ar file
operands are specified,
.Dv standard input
is read for a list of pathnames with one per line without any leading or
trailing
.Aq blanks .
.It Fl a
Append
.Ar files
to the end of an archive that was previously written.
If an archive format is not specified with a
.Fl x
option, the format currently being used in the archive will be selected.
Any attempt to append to an archive in a format different from the
format already used in the archive will cause 
.Nm pax
to exit immediately
with a non-zero exit status.
The blocking size used in the archive volume where writing starts
will continue to be used for the remainder of that archive volume.
.Pp
.Em Warning :
Many storage devices are not able to support the operations necessary
to perform an append operation.
Any attempt to append to an archive stored on such a device may damage the
archive or have other unpredictable results.
Tape drives in particular are more likely to not support an append operation.
An archive stored in a regular file system file or on a disk device will
usually support an append operation.
.It Fl b Ar blocksize
When
.Em writing
an archive,
block the output at a positive decimal integer number of
bytes per write to the archive file.
The
.Ar blocksize
must be a multiple of 512 bytes with a maximum of 32256 bytes.
A
.Ar blocksize
can end with
.Li k
or
.Li b
to specify multiplication by 1024 (1K) or 512, respectively.
A pair of
.Ar blocksizes
can be separated by
.Li x
to indicate a product.
A specific archive device may impose additional restrictions on the size
of blocking it will support.
When blocking is not specified, the default 
.Ar blocksize
is dependent on the specific archive format being used (see the
.Fl x
option).
.It Fl c
Match all file or archive members
.Em except
those specified by the
.Ar pattern
and
.Ar file
operands.
.It Fl d
Cause files of type directory being copied or archived, or archive members of
type directory being extracted, to match only the directory file or archive
member and not the file hierarchy rooted at the directory.
.It Fl f Ar archive
Specify
.Ar archive
as the pathname of the input or output archive, overriding the default
.Dv standard input
(for
.Em list
and
.Em read )
or
.Dv standard output
(for
.Em write ) .
A single archive may span multiple files and different archive devices.
When required,
.Nm pax
will prompt for the pathname of the file or device of the next volume in the
archive.
.It Fl i
Interactively rename files or archive members.
For each archive member matching a
.Ar pattern
operand or each file matching a
.Ar file
operand,
.Nm pax
will prompt to
.Pa /dev/tty
giving the name of the file, its file mode and its modification time.
.Nm Pax
will then read a line from
.Pa /dev/tty .
If this line is blank, the file or archive member is skipped.
If this line consists of a single period, the
file or archive member is processed with no modification to its name.
Otherwise, its name is replaced with the contents of the line.
.Nm Pax
will immediately exit with a non-zero exit status if 
.Dv <EOF>
is encountered when reading a response or if
.Pa /dev/tty
cannot be opened for reading and writing.
.It Fl k
Do not overwrite existing files.
.It Fl l
Link files. (The letter ell).
In the
.Em copy
mode (
.Fl r
.Fl w ) ,
hard links are made between the source and destination file hierarchies
whenever possible.
.It Fl n
Select the first archive member that matches each
.Ar pattern
operand.
No more than one archive member is matched for each
.Ar pattern .
When members of type directory are matched, the file hierarchy rooted at that
directory is also matched (unless
.Fl d 
is also specified).
.It Fl o Ar options
Information to modify the algorithm for extracting or writing archive files
which is specific to the archive format specified by
.Fl x .
In general,
.Ar options
take the form:
.Cm name=value
.It Fl p Ar string
Specify one or more file characteristic options (privileges).
The
.Ar string
option-argument is a string specifying file characteristics to be retained or
discarded on extraction.
The string consists of the specification characters
.Cm a , e , m , o ,
and
.Cm p .
Multiple characteristics can be concatenated within the same string
and multiple
.Fl p 
options can be specified.
The meaning of the specification characters are as follows:
.Bl -tag -width 2n
.It Cm a
Do not preserve file access times.
By default, file access times are preserved whenever possible.
.It Cm e
.Sq Preserve everything ,
the user ID, group ID, file mode bits,
file access time, and file modification time.
This is intended to be used by
.Em root ,
someone with all the appropriate privileges, in order to preserve all
aspects of the files as they are recorded in the archive.
The 
.Cm e
flag is the sum of the
.Cm o 
and
.Cm p
flags.
.It Cm m
Do not preserve file modification times.
By default, file modification times are preserved whenever possible.
.It Cm o
Preserve the user ID and group ID.
.It Cm p
.Sq Preserve
the file mode bits.
This intended to be used by a
.Em user 
with regular privileges who wants to preserve all aspects of the file other
than the ownership.
The file times are preserved by default, but two other flags are offered to
disable this and use the time of extraction instead.
.El
.Pp
In the preceding list,
.Sq preserve
indicates that an attribute stored in the archive is given to the
extracted file, subject to the permissions of the invoking
process.
Otherwise the attribute of the extracted file is determined as
part of the normal file creation action.
If neither the 
.Cm e
nor the
.Cm o
specification character is specified, or the user ID and group ID are not
preserved for any reason,
.Nm pax
will not set the
.Dv S_ISUID 
.Em ( setuid )
and
.Dv S_ISGID
.Em ( setgid )
bits of the file mode.
If the preservation of any of these items fails for any reason,
.Nm pax
will write a diagnostic message to
.Dv standard error .
Failure to preserve these items will affect the final exit status,
but will not cause the extracted file to be deleted.
If the file characteristic letters in any of the string option-arguments are