1237 lines
30 KiB
Groff
1237 lines
30 KiB
Groff
.\"-
|
|
.\" 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. 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
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd October 19, 2022
|
|
.Dt PAX 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pax
|
|
.Nd read and write file archives and copy directory hierarchies
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl cdnvzO
|
|
.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
|
|
.Fl r
|
|
.Op Fl cdiknuvzDOYZ
|
|
.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
|
|
.Fl w
|
|
.Op Fl dituvzHLOPX
|
|
.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
|
|
.Nm
|
|
.Fl r
|
|
.Fl w
|
|
.Op Fl diklntuvDHLOPXYZ
|
|
.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
|
|
.Ar directory
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility will read, write, and list the members of an archive file,
|
|
and will copy directory hierarchies.
|
|
These operations are independent of the specific archive format,
|
|
and support 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
|
|
will operate under:
|
|
.Em list , read , write ,
|
|
and
|
|
.Em copy .
|
|
.Bl -tag -width 6n
|
|
.It <none>
|
|
.Em List .
|
|
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 .
|
|
Extract 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 .
|
|
Write 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 .
|
|
Copy 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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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 64512 bytes.
|
|
A
|
|
.Ar blocksize
|
|
larger than 32256 bytes violates the
|
|
.Tn POSIX
|
|
standard and will not be portable to all systems.
|
|
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
|
|
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
|
|
will prompt to
|
|
.Pa /dev/tty
|
|
giving the name of the file, its file mode and its modification time.
|
|
The
|
|
.Nm
|
|
utility 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.
|
|
The
|
|
.Nm
|
|
utility 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
|
|
.Pq Fl r 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
|
|
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
|
|
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
|
|
duplicated or conflict with each other, the one(s) given last will take
|
|
precedence.
|
|
For example, if
|
|
.Dl Fl p Ar eme
|
|
is specified, file modification times are still preserved.
|
|
.Pp
|
|
File flags set by
|
|
.Xr chflags 1
|
|
are not understood by
|
|
.Nm ,
|
|
however
|
|
.Xr tar 1
|
|
and
|
|
.Xr dump 8
|
|
will preserve these.
|
|
.It Fl s Ar replstr
|
|
Modify the file or archive member names specified by the
|
|
.Ar pattern
|
|
or
|
|
.Ar file
|
|
operands according to the substitution expression
|
|
.Ar replstr ,
|
|
using the syntax of the
|
|
.Xr ed 1
|
|
utility regular expressions.
|
|
The format of these regular expressions are:
|
|
.Dl /old/new/[gp]
|
|
As in
|
|
.Xr ed 1 ,
|
|
.Cm old
|
|
is a basic regular expression and
|
|
.Cm new
|
|
can contain an ampersand (&), \\n (where n is a digit) back-references,
|
|
or subexpression matching.
|
|
The
|
|
.Cm old
|
|
string may also contain
|
|
.Dv <newline>
|
|
characters.
|
|
Any non-null character can be used as a delimiter (/ is shown here).
|
|
Multiple
|
|
.Fl s
|
|
expressions can be specified.
|
|
The expressions are applied in the order they are specified on the
|
|
command line, terminating with the first successful substitution.
|
|
The optional trailing
|
|
.Cm g
|
|
continues to apply the substitution expression to the pathname substring
|
|
which starts with the first character following the end of the last successful
|
|
substitution.
|
|
The first unsuccessful substitution stops the operation of the
|
|
.Cm g
|
|
option.
|
|
The optional trailing
|
|
.Cm p
|
|
will cause the final result of a successful substitution to be written to
|
|
.Dv standard error
|
|
in the following format:
|
|
.Dl <original pathname> >> <new pathname>
|
|
File or archive member names that substitute to the empty string
|
|
are not selected and will be skipped.
|
|
.It Fl t
|
|
Reset the access times of any file or directory read or accessed by
|
|
.Nm
|
|
to be the same as they were before being read or accessed by
|
|
.Nm .
|
|
.It Fl u
|
|
Ignore files that are older (having a less recent file modification time)
|
|
than a pre-existing file or archive member with the same name.
|
|
During
|
|
.Em read ,
|
|
an archive member with the same name as a file in the file system will be
|
|
extracted if the archive member is newer than the file.
|
|
During
|
|
.Em write ,
|
|
a file system member with the same name as an archive member will be
|
|
written to the archive if it is newer than the archive member.
|
|
During
|
|
.Em copy ,
|
|
the file in the destination hierarchy is replaced by the file in the source
|
|
hierarchy or by a link to the file in the source hierarchy if the file in
|
|
the source hierarchy is newer.
|
|
.It Fl v
|
|
During a
|
|
.Em list
|
|
operation, produce a verbose table of contents using the format of the
|
|
.Xr ls 1
|
|
utility with the
|
|
.Fl l
|
|
option.
|
|
For pathnames representing a hard link to a previous member of the archive,
|
|
the output has the format:
|
|
.Dl <ls -l listing> == <link name>
|
|
For pathnames representing a symbolic link, the output has the format:
|
|
.Dl <ls -l listing> => <link name>
|
|
Where <ls -l listing> is the output format specified by the
|
|
.Xr ls 1
|
|
utility when used with the
|
|
.Fl l
|
|
option.
|
|
Otherwise for all the other operational modes
|
|
.Em ( read , write ,
|
|
and
|
|
.Em copy ) ,
|
|
pathnames are written and flushed to
|
|
.Dv standard error
|
|
without a trailing
|
|
.Dv <newline>
|
|
as soon as processing begins on that file or
|
|
archive member.
|
|
The trailing
|
|
.Dv <newline> ,
|
|
is not buffered, and is written only after the file has been read or written.
|
|
.It Fl x Ar format
|
|
Specify the output archive format, with the default format being
|
|
.Ar ustar .
|
|
The
|
|
.Nm
|
|
utility currently supports the following formats:
|
|
.Bl -tag -width "sv4cpio"
|
|
.It Ar cpio
|
|
The extended cpio interchange format specified in the
|
|
.St -p1003.2
|
|
standard.
|
|
The default blocksize for this format is 5120 bytes.
|
|
Inode and device information about a file (used for detecting file hard links
|
|
by this format) which may be truncated by this format is detected by
|
|
.Nm
|
|
and is repaired.
|
|
.It Ar bcpio
|
|
The old binary cpio format.
|
|
The default blocksize for this format is 5120 bytes.
|
|
This format is not very portable and should not be used when other formats
|
|
are available.
|
|
Inode and device information about a file (used for detecting file hard links
|
|
by this format) which may be truncated by this format is detected by
|
|
.Nm
|
|
and is repaired.
|
|
.It Ar sv4cpio
|
|
The System V release 4 cpio.
|
|
The default blocksize for this format is 5120 bytes.
|
|
Inode and device information about a file (used for detecting file hard links
|
|
by this format) which may be truncated by this format is detected by
|
|
.Nm
|
|
and is repaired.
|
|
.It Ar sv4crc
|
|
The System V release 4 cpio with file crc checksums.
|
|
The default blocksize for this format is 5120 bytes.
|
|
Inode and device information about a file (used for detecting file hard links
|
|
by this format) which may be truncated by this format is detected by
|
|
.Nm
|
|
and is repaired.
|
|
.It Ar tar
|
|
The old
|
|
.Bx
|
|
tar format as found in
|
|
.Bx 4.3 .
|
|
The default blocksize for this format is 10240 bytes.
|
|
Pathnames stored by this format must be 100 characters or less in length.
|
|
Only
|
|
.Em regular
|
|
files,
|
|
.Em hard links , soft links ,
|
|
and
|
|
.Em directories
|
|
will be archived (other file system types are not supported).
|
|
For backwards compatibility with even older tar formats, a
|
|
.Fl o
|
|
option can be used when writing an archive to omit the storage of directories.
|
|
This option takes the form:
|
|
.Dl Fl o Cm write_opt=nodir
|
|
.It Ar ustar
|
|
The extended tar interchange format specified in the
|
|
.St -p1003.2
|
|
standard.
|
|
The default blocksize for this format is 10240 bytes.
|
|
Pathnames stored by this format must be 255 characters or less in length.
|
|
The directory part may be at most 155 characters and each path component
|
|
must be less than 100 characters.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility will detect and report any file that it is unable to store or extract
|
|
as the result of any specific archive format restrictions.
|
|
The individual archive formats may impose additional restrictions on use.
|
|
Typical archive format restrictions include (but are not limited to):
|
|
file pathname length, file size, link pathname length and the type of the file.
|
|
.It Fl z
|
|
Use
|
|
.Xr gzip 1
|
|
to compress (decompress) the archive while writing (reading).
|
|
Incompatible with
|
|
.Fl a .
|
|
.It Fl B Ar bytes
|
|
Limit the number of bytes written to a single archive volume to
|
|
.Ar bytes .
|
|
The
|
|
.Ar bytes
|
|
limit can end with
|
|
.Li m ,
|
|
.Li k ,
|
|
or
|
|
.Li b
|
|
to specify multiplication by 1048576 (1M), 1024 (1K) or 512, respectively.
|
|
A pair of
|
|
.Ar bytes
|
|
limits can be separated by
|
|
.Li x
|
|
to indicate a product.
|
|
.Pp
|
|
Note that the specified size is for the uncompressed pax image itself.
|
|
If the
|
|
.Fl z
|
|
option is also used, the resulting file may contain fewer
|
|
.Ar bytes ,
|
|
according to the compressibility of the archive contents.
|
|
See
|
|
.Xr zip 1 Pq Pa ports/archivers/zip
|
|
if compressed volumes of predictable size are required.
|
|
.Pp
|
|
.Em Warning :
|
|
Only use this option when writing an archive to a device which supports
|
|
an end of file read condition based on last (or largest) write offset
|
|
(such as a regular file or a tape drive).
|
|
The use of this option with a floppy or hard disk is not recommended.
|
|
.It Fl D
|
|
This option is the same as the
|
|
.Fl u
|
|
option, except that the file inode change time is checked instead of the
|
|
file modification time.
|
|
The file inode change time can be used to select files whose inode information
|
|
(e.g., uid, gid, etc.) is newer than a copy of the file in the destination
|
|
.Ar directory .
|
|
.It Fl E Ar limit
|
|
Limit the number of consecutive read faults while trying to read a flawed
|
|
archives to
|
|
.Ar limit .
|
|
With a positive
|
|
.Ar limit ,
|
|
.Nm
|
|
will attempt to recover from an archive read error and will
|
|
continue processing starting with the next file stored in the archive.
|
|
A
|
|
.Ar limit
|
|
of 0 will cause
|
|
.Nm
|
|
to stop operation after the first read error is detected on an archive volume.
|
|
A
|
|
.Ar limit
|
|
of
|
|
.Li NONE
|
|
will cause
|
|
.Nm
|
|
to attempt to recover from read errors forever.
|
|
The default
|
|
.Ar limit
|
|
is a small positive number of retries.
|
|
.Pp
|
|
.Em Warning :
|
|
Using this option with
|
|
.Li NONE
|
|
should be used with extreme caution as
|
|
.Nm
|
|
may get stuck in an infinite loop on a very badly flawed archive.
|
|
.It Fl G Ar group
|
|
Select a file based on its
|
|
.Ar group
|
|
name, or when starting with a
|
|
.Cm # ,
|
|
a numeric gid.
|
|
A '\\' can be used to escape the
|
|
.Cm # .
|
|
Multiple
|
|
.Fl G
|
|
options may be supplied and checking stops with the first match.
|
|
.It Fl H
|
|
Follow only command line symbolic links while performing a physical file
|
|
system traversal.
|
|
.It Fl L
|
|
Follow all symbolic links to perform a logical file system traversal.
|
|
.It Fl O
|
|
Force the archive to be one volume.
|
|
If a volume ends prematurely,
|
|
.Nm
|
|
will not prompt for a new volume.
|
|
This option can be useful for
|
|
automated tasks where error recovery cannot be performed by a human.
|
|
.It Fl P
|
|
Do not follow symbolic links, perform a physical file system traversal.
|
|
This is the default mode.
|
|
.It Fl T Ar [from_date][,to_date][/[c][m]]
|
|
Allow files to be selected based on a file modification or inode change
|
|
time falling within a specified time range of
|
|
.Ar from_date
|
|
to
|
|
.Ar to_date
|
|
(the dates are inclusive).
|
|
If only a
|
|
.Ar from_date
|
|
is supplied, all files with a modification or inode change time
|
|
equal to or younger are selected.
|
|
If only a
|
|
.Ar to_date
|
|
is supplied, all files with a modification or inode change time
|
|
equal to or older will be selected.
|
|
When the
|
|
.Ar from_date
|
|
is equal to the
|
|
.Ar to_date ,
|
|
only files with a modification or inode change time of exactly that
|
|
time will be selected.
|
|
.Pp
|
|
When
|
|
.Nm
|
|
is in the
|
|
.Em write
|
|
or
|
|
.Em copy
|
|
mode, the optional trailing field
|
|
.Ar [c][m]
|
|
can be used to determine which file time (inode change, file modification or
|
|
both) are used in the comparison.
|
|
If neither is specified, the default is to use file modification time only.
|
|
The
|
|
.Ar m
|
|
specifies the comparison of file modification time (the time when
|
|
the file was last written).
|
|
The
|
|
.Ar c
|
|
specifies the comparison of inode change time (the time when the file
|
|
inode was last changed; e.g., a change of owner, group, mode, etc).
|
|
When
|
|
.Ar c
|
|
and
|
|
.Ar m
|
|
are both specified, then the modification and inode change times are
|
|
both compared.
|
|
The inode change time comparison is useful in selecting files whose
|
|
attributes were recently changed or selecting files which were recently
|
|
created and had their modification time reset to an older time (as what
|
|
happens when a file is extracted from an archive and the modification time
|
|
is preserved).
|
|
Time comparisons using both file times is useful when
|
|
.Nm
|
|
is used to create a time based incremental archive (only files that were
|
|
changed during a specified time range will be archived).
|
|
.Pp
|
|
A time range is made up of six different fields and each field must contain two
|
|
digits.
|
|
The format is:
|
|
.Pp
|
|
.Dl [[[[[cc]yy]mm]dd]HH]MM[.SS]
|
|
.Pp
|
|
Where
|
|
.Ar cc
|
|
is the first two digits of the year (the century),
|
|
.Ar yy
|
|
is the last two digits of the year,
|
|
the first
|
|
.Ar mm
|
|
is the month (from 01 to 12),
|
|
.Ar dd
|
|
is the day of the month (from 01 to 31),
|
|
.Ar HH
|
|
is the hour of the day (from 00 to 23),
|
|
.Ar MM
|
|
is the minute (from 00 to 59),
|
|
and
|
|
.Ar SS
|
|
is the seconds (from 00 to 59).
|
|
The minute field
|
|
.Ar MM
|
|
is required, while the other fields are optional and must be added in the
|
|
following order:
|
|
.Ar HH , dd , mm , yy , cc .
|
|
The
|
|
.Cm ss
|
|
field may be added independently of the other fields.
|
|
Time ranges are relative to the current time, so
|
|
.Dl Fl T Ar 1234/cm
|
|
would select all files with a modification or inode change time
|
|
of 12:34 PM today or later.
|
|
Multiple
|
|
.Fl T
|
|
time range can be supplied and checking stops with the first match.
|
|
.It Fl U Ar user
|
|
Select a file based on its
|
|
.Ar user
|
|
name, or when starting with a
|
|
.Cm # ,
|
|
a numeric uid.
|
|
A '\\' can be used to escape the
|
|
.Cm # .
|
|
Multiple
|
|
.Fl U
|
|
options may be supplied and checking stops with the first match.
|
|
.It Fl X
|
|
When traversing the file hierarchy specified by a pathname,
|
|
do not descend into directories that have a different device ID.
|
|
See the
|
|
.Li st_dev
|
|
field as described in
|
|
.Xr stat 2
|
|
for more information about device ID's.
|
|
.It Fl Y
|
|
This option is the same as the
|
|
.Fl D
|
|
option, except that the inode change time is checked using the
|
|
pathname created after all the file name modifications have completed.
|
|
.It Fl Z
|
|
This option is the same as the
|
|
.Fl u
|
|
option, except that the modification time is checked using the
|
|
pathname created after all the file name modifications have completed.
|
|
.El
|
|
.Pp
|
|
The options that operate on the names of files or archive members
|
|
.Fl ( c ,
|
|
.Fl i ,
|
|
.Fl n ,
|
|
.Fl s ,
|
|
.Fl u ,
|
|
.Fl v ,
|
|
.Fl D ,
|
|
.Fl G ,
|
|
.Fl T ,
|
|
.Fl U ,
|
|
.Fl Y ,
|
|
and
|
|
.Fl Z )
|
|
interact as follows.
|
|
.Pp
|
|
When extracting files during a
|
|
.Em read
|
|
operation, archive members are
|
|
.Sq selected ,
|
|
based only on the user specified pattern operands as modified by the
|
|
.Fl c ,
|
|
.Fl n ,
|
|
.Fl u ,
|
|
.Fl D ,
|
|
.Fl G ,
|
|
.Fl T ,
|
|
.Fl U
|
|
options.
|
|
Then any
|
|
.Fl s
|
|
and
|
|
.Fl i
|
|
options will modify in that order, the names of these selected files.
|
|
Then the
|
|
.Fl Y
|
|
and
|
|
.Fl Z
|
|
options will be applied based on the final pathname.
|
|
Finally the
|
|
.Fl v
|
|
option will write the names resulting from these modifications.
|
|
.Pp
|
|
When archiving files during a
|
|
.Em write
|
|
operation, or copying files during a
|
|
.Em copy
|
|
operation, archive members are
|
|
.Sq selected ,
|
|
based only on the user specified pathnames as modified by the
|
|
.Fl n ,
|
|
.Fl u ,
|
|
.Fl D ,
|
|
.Fl G ,
|
|
.Fl T ,
|
|
and
|
|
.Fl U
|
|
options (the
|
|
.Fl D
|
|
option only applies during a copy operation).
|
|
Then any
|
|
.Fl s
|
|
and
|
|
.Fl i
|
|
options will modify in that order, the names of these selected files.
|
|
Then during a
|
|
.Em copy
|
|
operation the
|
|
.Fl Y
|
|
and the
|
|
.Fl Z
|
|
options will be applied based on the final pathname.
|
|
Finally the
|
|
.Fl v
|
|
option will write the names resulting from these modifications.
|
|
.Pp
|
|
When one or both of the
|
|
.Fl u
|
|
or
|
|
.Fl D
|
|
options are specified along with the
|
|
.Fl n
|
|
option, a file is not considered selected unless it is newer
|
|
than the file to which it is compared.
|
|
.Sh EXIT STATUS
|
|
The
|
|
.Nm
|
|
utility will exit with one of the following values:
|
|
.Bl -tag -width 2n
|
|
.It 0
|
|
All files were processed successfully.
|
|
.It 1
|
|
An error occurred.
|
|
.El
|
|
.Sh EXAMPLES
|
|
The command:
|
|
.Dl "pax -w -f /dev/sa0 ."
|
|
copies the contents of the current directory to the device
|
|
.Pa /dev/sa0 .
|
|
.Pp
|
|
The command:
|
|
.Dl pax -v -f filename
|
|
gives the verbose table of contents for an archive stored in
|
|
.Pa filename .
|
|
.Pp
|
|
The following commands:
|
|
.Dl mkdir /tmp/to
|
|
.Dl cd /tmp/from
|
|
.Dl pax -rw .\ /tmp/to
|
|
will copy the entire
|
|
.Pa /tmp/from
|
|
directory hierarchy to
|
|
.Pa /tmp/to .
|
|
.Pp
|
|
The command:
|
|
.Dl pax -r -s ',^//*usr//*,,' -f a.pax
|
|
reads the archive
|
|
.Pa a.pax ,
|
|
with all files rooted in ``/usr'' into the archive extracted relative to the
|
|
current directory.
|
|
.Pp
|
|
The command:
|
|
.Dl pax -rw -i .\ dest_dir
|
|
can be used to interactively select the files to copy from the current
|
|
directory to
|
|
.Pa dest_dir .
|
|
.Pp
|
|
The command:
|
|
.Dl pax -r -pe -U root -G bin -f a.pax
|
|
will extract all files from the archive
|
|
.Pa a.pax
|
|
which are owned by
|
|
.Em root
|
|
with group
|
|
.Em bin
|
|
and will preserve all file permissions.
|
|
.Pp
|
|
The command:
|
|
.Dl pax -r -w -v -Y -Z home /backup
|
|
will update (and list) only those files in the destination directory
|
|
.Pa /backup
|
|
which are older (less recent inode change or file modification times) than
|
|
files with the same name found in the source file tree
|
|
.Pa home .
|
|
.Sh DIAGNOSTICS
|
|
Whenever
|
|
.Nm
|
|
cannot create a file or a link when reading an archive or cannot
|
|
find a file when writing an archive, or cannot preserve the user ID,
|
|
group ID, or file mode when the
|
|
.Fl p
|
|
option is specified, a diagnostic message is written to
|
|
.Dv standard error
|
|
and a non-zero exit status will be returned, but processing will continue.
|
|
In the case where pax cannot create a link to a file,
|
|
.Nm
|
|
will not create a second copy of the file.
|
|
.Pp
|
|
If the extraction of a file from an archive is prematurely terminated by
|
|
a signal or error,
|
|
.Nm
|
|
may have only partially extracted a file the user wanted.
|
|
Additionally, the file modes of extracted files and directories
|
|
may have incorrect file bits, and the modification and access times may be
|
|
wrong.
|
|
.Pp
|
|
If the creation of an archive is prematurely terminated by a signal or error,
|
|
.Nm
|
|
may have only partially created the archive which may violate the specific
|
|
archive format specification.
|
|
.Pp
|
|
If while doing a
|
|
.Em copy ,
|
|
.Nm
|
|
detects a file is about to overwrite itself, the file is not copied,
|
|
a diagnostic message is written to
|
|
.Dv standard error
|
|
and when
|
|
.Nm
|
|
completes it will exit with a non-zero exit status.
|
|
.Sh SEE ALSO
|
|
.Xr cpio 1 ,
|
|
.Xr tar 1
|
|
.Sh STANDARDS
|
|
The
|
|
.Nm
|
|
utility is a superset of the
|
|
.St -p1003.2
|
|
standard.
|
|
The options
|
|
.Fl z ,
|
|
.Fl B ,
|
|
.Fl D ,
|
|
.Fl E ,
|
|
.Fl G ,
|
|
.Fl H ,
|
|
.Fl L ,
|
|
.Fl O ,
|
|
.Fl P ,
|
|
.Fl T ,
|
|
.Fl U ,
|
|
.Fl Y ,
|
|
.Fl Z ,
|
|
the archive formats
|
|
.Ar bcpio ,
|
|
.Ar sv4cpio ,
|
|
.Ar sv4crc ,
|
|
.Ar tar ,
|
|
and the flawed archive handling during
|
|
.Ar list
|
|
and
|
|
.Ar read
|
|
operations are extensions to the
|
|
.Tn POSIX
|
|
standard.
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility appeared in
|
|
.Bx 4.4 .
|
|
.Sh AUTHORS
|
|
.An Keith Muller
|
|
at the University of California, San Diego
|
|
.Sh BUGS
|
|
The
|
|
.Nm
|
|
utility does not recognize multibyte characters.
|
|
.Pp
|
|
File flags set by
|
|
.Xr chflags 1
|
|
are not preserved by
|
|
.Nm .
|
|
The BUGS section of
|
|
.Xr chflags 1
|
|
has a list of utilities that are unaware of flags.
|