1424 lines
37 KiB
Groff
1424 lines
37 KiB
Groff
.nr g 2
|
||
.\" $MirOS: src/bin/pax/pax.1,v 1.34 2018/12/25 19:38:10 tg Exp $
|
||
.\" $OpenBSD: pax.1,v 1.74 2018/07/23 19:02:49 kn Exp $
|
||
.\" $NetBSD: pax.1,v 1.3 1995/03/21 09:07:37 cgd Exp $
|
||
.\"
|
||
.\" Copyright (c) 2005, 2009, 2011, 2012, 2014, 2016, 2017, 2018
|
||
.\" mirabilos <m@mirbsd.org>
|
||
.\" 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
|
||
.\"
|
||
.\"-
|
||
.\" Try to make GNU groff and AT&T nroff more compatible
|
||
.\" * ` generates ‘ in gnroff, so use \`
|
||
.\" * ' generates ’ in gnroff, \' generates ´, so use \*(aq
|
||
.\" * - generates ‐ in gnroff, \- generates −, so .tr it to -
|
||
.\" thus use - for hyphens and \- for minus signs and option dashes
|
||
.\" * ~ is size-reduced and placed atop in groff, so use \*(TI
|
||
.\" * ^ is size-reduced and placed atop in groff, so use \*(ha
|
||
.\" * \(en does not work in nroff, so use \*(en
|
||
.\" * <>| are problematic, so redefine and use \*(Lt\*(Gt\*(Ba
|
||
.\" Also make sure to use \& *before* a punctuation char that is to not
|
||
.\" be interpreted as punctuation, and especially with two-letter words
|
||
.\" but also (after) a period that does not end a sentence (“e.g.\&”).
|
||
.\" The section after the "doc" macropackage has been loaded contains
|
||
.\" additional code to convene between the UCB mdoc macropackage (and
|
||
.\" its variant as BSD mdoc in groff) and the GNU mdoc macropackage.
|
||
.\"
|
||
.ie \n(.g \{\
|
||
. if \*[.T]ascii .tr \-\N'45'
|
||
. if \*[.T]latin1 .tr \-\N'45'
|
||
. if \*[.T]utf8 .tr \-\N'45'
|
||
. ds <= \[<=]
|
||
. ds >= \[>=]
|
||
. ds Rq \[rq]
|
||
. ds Lq \[lq]
|
||
. ds sL \(aq
|
||
. ds sR \(aq
|
||
. if \*[.T]utf8 .ds sL `
|
||
. if \*[.T]ps .ds sL `
|
||
. if \*[.T]utf8 .ds sR '
|
||
. if \*[.T]ps .ds sR '
|
||
. ds aq \(aq
|
||
. ds TI \(ti
|
||
. ds ha \(ha
|
||
. ds en \(en
|
||
.\}
|
||
.el \{\
|
||
. ds aq '
|
||
. ds TI ~
|
||
. ds ha ^
|
||
. ds en \(em
|
||
.\}
|
||
.\"
|
||
.\" Implement .Dd with the Mdocdate RCS keyword
|
||
.\"
|
||
.rn Dd xD
|
||
.de Dd
|
||
.ie \\$1$Mdocdate: \{\
|
||
. xD \\$2 \\$3, \\$4
|
||
.\}
|
||
.el .xD \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8
|
||
..
|
||
.\"
|
||
.\" .Dd must come before definition of .Mx, because when called
|
||
.\" with -mandoc, it might implement .Mx itself, but we want to
|
||
.\" use our own definition. And .Dd must come *first*, always.
|
||
.\"
|
||
.Dd $Mdocdate: December 25 2018 $
|
||
.\"
|
||
.\" Check which macro package we use, and do other -mdoc setup.
|
||
.\"
|
||
.ie \n(.g \{\
|
||
. if \*[.T]utf8 .tr \[la]\*(Lt
|
||
. if \*[.T]utf8 .tr \[ra]\*(Gt
|
||
. ie d volume-ds-1 .ds tT gnu
|
||
. el .ie d doc-volume-ds-1 .ds tT gnp
|
||
. el .ds tT bsd
|
||
.\}
|
||
.el .ds tT ucb
|
||
.\"
|
||
.\" Implement .Mx (MirBSD)
|
||
.\"
|
||
.ie "\*(tT"gnu" \{\
|
||
. eo
|
||
. de Mx
|
||
. nr curr-font \n[.f]
|
||
. nr curr-size \n[.ps]
|
||
. ds str-Mx \f[\n[curr-font]]\s[\n[curr-size]u]
|
||
. ds str-Mx1 \*[Tn-font-size]\%MirBSD\*[str-Mx]
|
||
. if !\n[arg-limit] \
|
||
. if \n[.$] \{\
|
||
. ds macro-name Mx
|
||
. parse-args \$@
|
||
. \}
|
||
. if (\n[arg-limit] > \n[arg-ptr]) \{\
|
||
. nr arg-ptr +1
|
||
. ie (\n[type\n[arg-ptr]] == 2) \
|
||
. as str-Mx1 \~\*[arg\n[arg-ptr]]
|
||
. el \
|
||
. nr arg-ptr -1
|
||
. \}
|
||
. ds arg\n[arg-ptr] "\*[str-Mx1]
|
||
. nr type\n[arg-ptr] 2
|
||
. ds space\n[arg-ptr] "\*[space]
|
||
. nr num-args (\n[arg-limit] - \n[arg-ptr])
|
||
. nr arg-limit \n[arg-ptr]
|
||
. if \n[num-args] \
|
||
. parse-space-vector
|
||
. print-recursive
|
||
..
|
||
. ec
|
||
. ds sP \s0
|
||
. ds tN \*[Tn-font-size]
|
||
.\}
|
||
.el .ie "\*(tT"gnp" \{\
|
||
. eo
|
||
. de Mx
|
||
. nr doc-curr-font \n[.f]
|
||
. nr doc-curr-size \n[.ps]
|
||
. ds doc-str-Mx \f[\n[doc-curr-font]]\s[\n[doc-curr-size]u]
|
||
. ds doc-str-Mx1 \*[doc-Tn-font-size]\%MirBSD\*[doc-str-Mx]
|
||
. if !\n[doc-arg-limit] \
|
||
. if \n[.$] \{\
|
||
. ds doc-macro-name Mx
|
||
. doc-parse-args \$@
|
||
. \}
|
||
. if (\n[doc-arg-limit] > \n[doc-arg-ptr]) \{\
|
||
. nr doc-arg-ptr +1
|
||
. ie (\n[doc-type\n[doc-arg-ptr]] == 2) \
|
||
. as doc-str-Mx1 \~\*[doc-arg\n[doc-arg-ptr]]
|
||
. el \
|
||
. nr doc-arg-ptr -1
|
||
. \}
|
||
. ds doc-arg\n[doc-arg-ptr] "\*[doc-str-Mx1]
|
||
. nr doc-type\n[doc-arg-ptr] 2
|
||
. ds doc-space\n[doc-arg-ptr] "\*[doc-space]
|
||
. nr doc-num-args (\n[doc-arg-limit] - \n[doc-arg-ptr])
|
||
. nr doc-arg-limit \n[doc-arg-ptr]
|
||
. if \n[doc-num-args] \
|
||
. doc-parse-space-vector
|
||
. doc-print-recursive
|
||
..
|
||
. ec
|
||
. ds sP \s0
|
||
. ds tN \*[doc-Tn-font-size]
|
||
.\}
|
||
.el \{\
|
||
. de Mx
|
||
. nr cF \\n(.f
|
||
. nr cZ \\n(.s
|
||
. ds aa \&\f\\n(cF\s\\n(cZ
|
||
. if \\n(aC==0 \{\
|
||
. ie \\n(.$==0 \&MirBSD\\*(aa
|
||
. el .aV \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
|
||
. \}
|
||
. if \\n(aC>\\n(aP \{\
|
||
. nr aP \\n(aP+1
|
||
. ie \\n(C\\n(aP==2 \{\
|
||
. as b1 \&MirBSD\ #\&\\*(A\\n(aP\\*(aa
|
||
. ie \\n(aC>\\n(aP \{\
|
||
. nr aP \\n(aP+1
|
||
. nR
|
||
. \}
|
||
. el .aZ
|
||
. \}
|
||
. el \{\
|
||
. as b1 \&MirBSD\\*(aa
|
||
. nR
|
||
. \}
|
||
. \}
|
||
..
|
||
.\}
|
||
.\"-
|
||
.ie \ng==1 \{\
|
||
. ds nc mircpio
|
||
. ds np mirpax
|
||
. ds nt mirtar
|
||
. ds nm mirpax
|
||
. Dt MIRPAX 1
|
||
.\}
|
||
.el .ie \ng==2 \{\
|
||
. ds nc paxcpio
|
||
. ds np pax
|
||
. ds nt paxtar
|
||
. ds nm pax
|
||
. Dt PAX 1
|
||
.\}
|
||
.el \{\
|
||
. ds nc cpio
|
||
. ds np pax
|
||
. ds nt tar
|
||
. ds nm pax
|
||
. Dt PAX 1
|
||
.\}
|
||
.\"-
|
||
.Os MirBSD
|
||
.Sh NAME
|
||
.ie \ng==1 \{\
|
||
.Nm mirpax
|
||
.Nd read and write file archives and copy directory hierarchies
|
||
.\}
|
||
.el \{\
|
||
.Nm pax
|
||
.Nd read and write file archives and copy directory hierarchies
|
||
.\}
|
||
.Sh SYNOPSIS
|
||
.Bk -words
|
||
.Nm \*(nm
|
||
.Op Fl 0cdJjnOvz
|
||
.Op Fl E Ar limit
|
||
.Op Fl f Ar archive
|
||
.Op Fl G Ar group
|
||
.Op Fl s Ar replstr
|
||
.Op Fl T Ar range
|
||
.Op Fl U Ar user
|
||
.Op Ar pattern ...
|
||
.Nm \*(nm
|
||
.Fl r
|
||
.Op Fl 0cDdiJjknOuvYZz
|
||
.Op Fl E Ar limit
|
||
.Op Fl f Ar archive
|
||
.Op Fl G Ar group
|
||
.Op Fl M Ar flag
|
||
.Op Fl o Ar options
|
||
.Op Fl p Ar string
|
||
.Op Fl s Ar replstr
|
||
.Op Fl T Ar range
|
||
.Op Fl U Ar user
|
||
.Op Ar pattern ...
|
||
.Nm \*(nm
|
||
.Fl w
|
||
.Op Fl 0adHiJjLOPtuvXz
|
||
.Op Fl B Ar bytes
|
||
.Op Fl b Ar blocksize
|
||
.Op Fl f Ar archive
|
||
.Op Fl G Ar group
|
||
.Op Fl M Ar flag
|
||
.Op Fl o Ar options
|
||
.Op Fl s Ar replstr
|
||
.Op Fl T Ar range
|
||
.Op Fl U Ar user
|
||
.Op Fl x Ar format
|
||
.Op Ar
|
||
.Nm \*(nm
|
||
.Fl rw
|
||
.Op Fl 0DdHiJjkLlnOPtuvXYZ
|
||
.Op Fl G Ar group
|
||
.Op Fl p Ar string
|
||
.Op Fl s Ar replstr
|
||
.Op Fl T Ar range
|
||
.Op Fl U Ar user
|
||
.Op Ar
|
||
.Ar directory
|
||
.Ek
|
||
.Sh DESCRIPTION
|
||
.Nm
|
||
will read, write, and list the members of an archive file
|
||
and will copy directory hierarchies.
|
||
.Nm
|
||
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
|
||
will operate under:
|
||
.Em list , read , write ,
|
||
and
|
||
.Em copy .
|
||
.Bl -tag -width 6n
|
||
.It Aq none
|
||
.Em List .
|
||
.Nm
|
||
will write to standard output
|
||
a table of contents of the members of the archive file read from
|
||
standard input, whose pathnames match the specified
|
||
.Ar pattern
|
||
arguments.
|
||
The table of contents contains one filename per line
|
||
and is written using single line buffering.
|
||
.It Fl r
|
||
.Em Read .
|
||
.Nm
|
||
extracts the members of the archive file read from the standard input,
|
||
with pathnames matching the specified
|
||
.Ar pattern
|
||
arguments.
|
||
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
|
||
writes an archive containing the
|
||
.Ar file
|
||
operands to 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
|
||
standard input.
|
||
When a
|
||
.Ar file
|
||
operand is also a directory, the entire file hierarchy rooted
|
||
at that directory will be included.
|
||
.It Fl rw
|
||
.Em Copy .
|
||
.Nm
|
||
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 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
|
||
.Sy 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 read or 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).
|
||
.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
|
||
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 glob 7 .
|
||
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 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 standard error
|
||
and then exit with a non-zero exit status.
|
||
.Pp
|
||
The options are as follows:
|
||
.Bl -tag -width Ds
|
||
.It Fl 0
|
||
Use the NUL
|
||
.Pq Ql \e0
|
||
character as a pathname terminator, instead of newline
|
||
.Pq Ql \en .
|
||
This applies only to the pathnames read from standard input in
|
||
the write and copy modes,
|
||
and to the pathnames written to standard output in list mode.
|
||
This option is expected to be used in concert with the
|
||
.Fl print0
|
||
function in
|
||
.Xr find 1 ,
|
||
the
|
||
.Fl d Ar \*(aq\*(aq
|
||
option to the
|
||
.Ic read
|
||
built-in utility of
|
||
.Xr mksh 1
|
||
or the
|
||
.Fl 0
|
||
flag in
|
||
.Xr xargs 1 .
|
||
.It Fl a
|
||
Append the given
|
||
.Ar file
|
||
operands
|
||
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
|
||
.Sy 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 filesystem file or on a disk device will
|
||
usually support an append operation.
|
||
.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
|
||
.Sq Li m ,
|
||
.Sq Li k ,
|
||
or
|
||
.Sq Li b
|
||
to specify multiplication by 1048576 (1M), 1024 (1K) or 512, respectively.
|
||
A pair of
|
||
.Ar bytes
|
||
limits can be separated by
|
||
.Sq Li x
|
||
to indicate a product.
|
||
.Pp
|
||
.Sy 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 b Ar blocksize
|
||
When 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.
|
||
Archive block sizes larger than 32256 bytes violate the
|
||
.Tn POSIX
|
||
standard and will not be portable to all systems.
|
||
A
|
||
.Ar blocksize
|
||
can end with
|
||
.Sq Li k
|
||
or
|
||
.Sq Li b
|
||
to specify multiplication by 1024 (1K) or 512, respectively.
|
||
A pair of
|
||
.Ar blocksize Ns s
|
||
can be separated by
|
||
.Sq 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
|
||
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 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 E Ar limit
|
||
Limit the number of consecutive read faults while trying to read a flawed
|
||
archive 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.
|
||
The default
|
||
.Ar limit
|
||
is a small positive number of retries.
|
||
.It Fl f Ar archive
|
||
Specify
|
||
.Ar archive
|
||
as the pathname of the input or output archive, overriding the default
|
||
standard input (for list and read)
|
||
or standard output
|
||
(for 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 G Ar group
|
||
Select a file based on its
|
||
.Ar group
|
||
name, or when starting with a
|
||
.Cm # ,
|
||
a numeric GID.
|
||
A
|
||
.Ql \e
|
||
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 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.
|
||
.Nm
|
||
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
|
||
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 J
|
||
Use the xz utility to compress (decompress) the archive
|
||
while writing (reading).
|
||
Incompatible with
|
||
.Fl a .
|
||
.It Fl j
|
||
Use the bzip2 utility to compress (decompress) the archive
|
||
while writing (reading).
|
||
Incompatible with
|
||
.Fl a .
|
||
.It Fl k
|
||
Do not overwrite existing files.
|
||
.It Fl L
|
||
Follow all symbolic links to perform a logical filesystem traversal.
|
||
.It Fl l
|
||
(The lowercase letter
|
||
.Dq ell . )
|
||
Link files.
|
||
In copy mode
|
||
.Pq Fl r Fl w ,
|
||
hard links are made between the source and destination file hierarchies
|
||
whenever possible.
|
||
.It Fl M Ar flag
|
||
Configure the archive normaliser.
|
||
.Ar flag
|
||
is either a numeric value compatible to
|
||
.Xr strtonum 3
|
||
which is directly stored in the flags word, or
|
||
one of the following values, optionally prefixed with
|
||
.Dq no\-
|
||
to turn them off:
|
||
.Pp
|
||
.Bl -tag -width xxxxxx -compact
|
||
.It Ar inodes
|
||
0x0001: Serialise inodes, zero device info.
|
||
.br
|
||
(cpio, sv4cpio, sv4crc)
|
||
.It Ar links
|
||
0x0002: Store content of hard links only once.
|
||
.br
|
||
(cpio, sv4cpio, sv4crc)
|
||
.It Ar mtime
|
||
0x0004: Zero out the file modification time.
|
||
.br
|
||
(ar, cpio, sv4cpio, sv4crc, ustar)
|
||
.It Ar uidgid
|
||
0x0008: Set owner to 0:0
|
||
.Pq Li root Ns : Ns Li wheel .
|
||
.br
|
||
(ar, cpio, sv4cpio, sv4crc, ustar)
|
||
.It Ar verb
|
||
0x0010: Debug this option.
|
||
.It Ar debug
|
||
0x0020: Debug file header storage.
|
||
.It Ar lncp
|
||
0x0040: Extract hard links by copy if link fails.
|
||
.It Ar numid
|
||
0x0080: Use only numeric uid and gid values.
|
||
.br
|
||
(ustar)
|
||
.It Ar gslash
|
||
0x0100: Append a slash after directory names.
|
||
.br
|
||
(ustar)
|
||
.It Ar set
|
||
0x0003: Keep ownership and mtime intact.
|
||
.It Ar dist
|
||
0x008B: Clean everything except mtime.
|
||
.It Ar norm
|
||
0x008F: Clean everything.
|
||
.It Ar root
|
||
0x0089: Clean owner and device information.
|
||
.El
|
||
.Pp
|
||
When creating an archive and verbosely listing output, these
|
||
normalisation operations are not reflected in the output,
|
||
because they are made only after the output has been shown.
|
||
.Pp
|
||
This option is only implemented for the ar, cpio, sv4cpio,
|
||
sv4crc, and ustar file format writing routines.
|
||
.Pp
|
||
TODO: The
|
||
.Nm \*(nm
|
||
frontend should be using the
|
||
.Fl o
|
||
option for handling this feature instead.
|
||
.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
|
||
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 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:
|
||
.Ar name Ns = Ns Ar value .
|
||
.Pp
|
||
The following options are available for the
|
||
.Cm ustar
|
||
and old
|
||
.Bx
|
||
.Cm tar
|
||
formats:
|
||
.Pp
|
||
.Bl -tag -width Ds -compact
|
||
.It Cm write_opt=nodir
|
||
When writing archives, omit the storage of directories.
|
||
.El
|
||
.It Fl P
|
||
Do not follow symbolic links, perform a physical filesystem traversal.
|
||
This is the default mode.
|
||
.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 meanings 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
|
||
.Dq Preserve everything ,
|
||
the user ID, group ID, file mode bits,
|
||
file access time, and file modification time.
|
||
This is intended to be used by 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
|
||
.Dq Preserve
|
||
the file mode bits.
|
||
This is intended to be used by a 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
|
||
(setuid) and
|
||
.Dv S_ISGID
|
||
(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 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
|
||
.Fl p Ar eme
|
||
is specified, file modification times are still preserved.
|
||
.It Fl r
|
||
Read an archive file from standard input
|
||
and extract the specified
|
||
.Ar file
|
||
operands.
|
||
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 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 standard error
|
||
and exit with a non-zero exit status at the completion of operation.
|
||
.It Fl s Ar replstr
|
||
Modify the archive member names according to the substitution expression
|
||
.Ar replstr ,
|
||
using the syntax of the
|
||
.Xr ed 1
|
||
utility regular expressions.
|
||
.Ar file
|
||
or
|
||
.Ar pattern
|
||
arguments may be given to restrict the list of archive members to those
|
||
specified.
|
||
.Pp
|
||
The format of these regular expressions is:
|
||
.Pp
|
||
.Dl /old/new/[gp]
|
||
.Pp
|
||
As in
|
||
.Xr ed 1 ,
|
||
.Ar old
|
||
is a basic regular expression (see
|
||
.Xr re_format 7 )
|
||
and
|
||
.Ar new
|
||
can contain an ampersand
|
||
.Pq Ql & ,
|
||
.Ql \e Ns Em n
|
||
(where
|
||
.Em n
|
||
is a digit) back-references,
|
||
or subexpression matching.
|
||
The
|
||
.Ar old
|
||
string may also contain newline characters.
|
||
Any non-null character can be used as a delimiter
|
||
.Po
|
||
.Ql /
|
||
is shown here
|
||
.Pc .
|
||
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.
|
||
.Pp
|
||
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
|
||
standard error in the following format:
|
||
.Pp
|
||
.D1 Em original-pathname No \*(Gt\*(Gt Em new-pathname
|
||
.Pp
|
||
File or archive member names that substitute to the empty string
|
||
are not selected and will be skipped.
|
||
.It Fl T Ar range
|
||
Allow files to be selected based on a file modification or inode change
|
||
time falling within the specified time range.
|
||
The range has the format:
|
||
.Sm off
|
||
.Bd -filled -offset indent
|
||
.Oo Ar from_date Oc Oo ,
|
||
.Ar to_date Oc Oo /
|
||
.Oo Cm c Oc Op Cm m Oc
|
||
.Ed
|
||
.Sm on
|
||
.Pp
|
||
The dates specified by
|
||
.Ar from_date
|
||
to
|
||
.Ar to_date
|
||
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 write or copy mode, the optional trailing field
|
||
.Oo Cm c Oc Ns Op Cm 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
|
||
.Cm m
|
||
specifies the comparison of file modification time (the time when
|
||
the file was last written).
|
||
The
|
||
.Cm 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
|
||
.Cm c
|
||
and
|
||
.Cm m
|
||
are both specified, then the modification and inode change times are
|
||
both compared.
|
||
.Pp
|
||
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 ,
|
||
.Ar yy , cc .
|
||
.Pp
|
||
The
|
||
.Ar SS
|
||
field may be added independently of the other fields.
|
||
Time ranges are relative to the current time, so
|
||
.Ic \-T 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 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 \*(nm .
|
||
.It Fl U Ar user
|
||
Select a file based on its
|
||
.Ar user
|
||
name, or when starting with a
|
||
.Cm # ,
|
||
a numeric UID.
|
||
A
|
||
.Ql \e
|
||
can be used to escape the
|
||
.Cm # .
|
||
Multiple
|
||
.Fl U
|
||
options may be supplied and checking stops with the first match.
|
||
.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 read,
|
||
an archive member with the same name as a file in the filesystem will be
|
||
extracted if the archive member is newer than the file.
|
||
During write,
|
||
a filesystem member with the same name as an archive member will be
|
||
written to the archive if it is newer than the archive member.
|
||
During 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 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:
|
||
.Pp
|
||
.Dl Em ls \-l listing No == Em link-name
|
||
.Pp
|
||
For pathnames representing a symbolic link, the output has the format:
|
||
.Pp
|
||
.Dl Em ls \-l listing No -\*(Gt Em link-name
|
||
.Pp
|
||
Where
|
||
.Em 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
|
||
(read, write, and copy),
|
||
pathnames are written and flushed to standard error
|
||
without a trailing newline
|
||
as soon as processing begins on that file or
|
||
archive member.
|
||
The trailing newline
|
||
is not buffered and is written only after the file has been read or written.
|
||
.It Fl w
|
||
Write files to the standard output
|
||
in the specified archive format.
|
||
When no
|
||
.Ar file
|
||
operands are specified, standard input
|
||
is read for a list of pathnames with one per line without any leading or
|
||
trailing
|
||
.Aq blanks .
|
||
.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 IDs.
|
||
.It Fl x Ar format
|
||
Specify the output archive format, with the default format being
|
||
.Cm ustar .
|
||
.Nm
|
||
currently supports the following formats:
|
||
.Bl -tag -width "sv4cpio"
|
||
.It Cm ar
|
||
The Unix Archiver library format.
|
||
This format matches APT repositories and the BSD
|
||
.Xr ar 1
|
||
specification, not GNU binutils (which can however read them) or SYSV systems.
|
||
See
|
||
.Xr ar 5
|
||
on some operating systems for more information.
|
||
.It Cm 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 Cm 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 Cm 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 Cm 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 Cm 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 regular files, hard links, soft links, and directories
|
||
will be archived (other filesystem 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:
|
||
.Pp
|
||
.Dl Fl o Cm write_opt=nodir
|
||
.It Cm ustar
|
||
The extended tar interchange format specified in the
|
||
.St -p1003.2
|
||
standard.
|
||
The default blocksize for this format is 10240 bytes.
|
||
Filenames stored by this format must be 100 characters or less in length;
|
||
the total pathname must be 256 characters or less.
|
||
.El
|
||
.Pp
|
||
.Nm
|
||
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 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.
|
||
.It Fl z
|
||
Use the
|
||
.Xr gzip 1
|
||
utility to compress (decompress) the archive while writing (reading).
|
||
Incompatible with
|
||
.Fl a .
|
||
.El
|
||
.Pp
|
||
The options that operate on the names of files or archive members
|
||
.Po 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
|
||
.Pc
|
||
interact as follows.
|
||
.Pp
|
||
When extracting files during a 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 write operation,
|
||
or copying files during a 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 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 ENVIRONMENT
|
||
.Bl -tag -width Fl
|
||
.It Ev TMPDIR
|
||
Path in which to store temporary files.
|
||
.El
|
||
.Sh EXIT STATUS
|
||
.Ex -std pax
|
||
.Sh EXAMPLES
|
||
Copy the contents of the current directory to the device
|
||
.Pa /dev/rst0 :
|
||
.Pp
|
||
.Dl $ \*(nm \-w \-f /dev/rst0 \&.
|
||
.Pp
|
||
Give the verbose table of contents for an archive stored in
|
||
.Pa filename :
|
||
.Pp
|
||
.Dl $ \*(nm \-v \-f filename
|
||
.Pp
|
||
This sequence of commands will copy the entire
|
||
.Pa olddir
|
||
directory hierarchy to
|
||
.Pa newdir :
|
||
.Bd -literal -offset indent
|
||
$ mkdir newdir
|
||
$ cd olddir
|
||
$ \*(nm \-rw . ../newdir
|
||
.Ed
|
||
.Pp
|
||
Extract files from the archive
|
||
.Pa a.pax .
|
||
Files rooted in
|
||
.Pa /usr
|
||
are extracted relative to the current working directory;
|
||
all other files are extracted to their unmodified path.
|
||
.Pp
|
||
.Dl $ \*(nm \-r \-s \*(aq,\*(ha/usr/,,\*(aq \-f a.pax
|
||
.Pp
|
||
This can be used to interactively select the files to copy from the
|
||
current directory to
|
||
.Pa dest_dir :
|
||
.Pp
|
||
.Dl $ \*(nm \-rw \-i \&. dest_dir
|
||
.Pp
|
||
Extract all files from the archive
|
||
.Pa a.pax
|
||
which are owned by
|
||
.Em root
|
||
with group
|
||
.Em bin
|
||
and preserve all file permissions:
|
||
.Pp
|
||
.Dl "$ \*(nm \-r \-pe \-U root \-G bin \-f a.pax"
|
||
.Pp
|
||
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 :
|
||
.Pp
|
||
.Dl "$ \*(nm \-r \-w \-v \-Y \-Z home /backup"
|
||
.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 standard error
|
||
and a non-zero exit status will be returned, but processing will continue.
|
||
In the case where
|
||
.Nm
|
||
cannot create a link to a file,
|
||
unless
|
||
.Fl M Ar lncp
|
||
is given,
|
||
.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 copy,
|
||
.Nm
|
||
detects a file is about to overwrite itself, the file is not copied,
|
||
a diagnostic message is written to standard error
|
||
and when
|
||
.Nm
|
||
completes it will exit with a non-zero exit status.
|
||
.Sh SEE ALSO
|
||
.Xr ar 1 ,
|
||
.Xr cpio 1 ,
|
||
.if \ng==1 \{\
|
||
.Xr deb 5 ,
|
||
.Xr mircpio 1 ,
|
||
.Xr mirtar 1 ,
|
||
.Xr pax 1 ,
|
||
.\}
|
||
.if \ng==2 \{\
|
||
.Xr deb 5 ,
|
||
.Xr paxcpio 1 ,
|
||
.Xr paxtar 1 ,
|
||
.\}
|
||
.Xr tar 1
|
||
.Sh STANDARDS
|
||
The
|
||
.Nm
|
||
utility is mostly compliant with an older version of the IEEE Std 1003.1
|
||
.Pq Dq Tn POSIX
|
||
specification,
|
||
except for the known
|
||
.Sx BUGS
|
||
listed below, and that the
|
||
.Cm pax
|
||
archive format and the
|
||
.Cm listopt
|
||
keyword are unsupported.
|
||
.Pp
|
||
The flags
|
||
.Fl 0BDEGHJjLMOPTUYZz ,
|
||
the archive formats
|
||
.Cm ar ,
|
||
.Cm bcpio ,
|
||
.Cm sv4cpio ,
|
||
.Cm sv4crc
|
||
and
|
||
.Cm tar ,
|
||
the
|
||
.Cm b , k ,
|
||
and
|
||
.Cm x
|
||
additions to the
|
||
.Fl b
|
||
flag
|
||
and the flawed archive handling during list and read operations
|
||
are extensions to that specification.
|
||
.Sh HISTORY
|
||
A
|
||
.Nm
|
||
utility appeared in
|
||
.Bx 4.4 .
|
||
.Sh AUTHORS
|
||
.An -nosplit
|
||
.An Keith Muller
|
||
at the University of California, San Diego.
|
||
.Mx
|
||
extensions by
|
||
.An mirabilos Aq m@mirbsd.org .
|
||
.Sh BUGS
|
||
The pattern matching does not match either
|
||
.Tn POSIX
|
||
or this documentation completely.
|
||
See also
|
||
.Sx STANDARDS
|
||
above.
|