aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2014-01-30 11:10:26 +0200
committerSergey Poznyakoff <gray@gnu.org.ua>2014-01-30 12:13:28 +0200
commita3987da2a573bd2438f15df6faa680922025be18 (patch)
treeccab2a2da1af43253e8027f89ea3703a3f3672bd
parent69014cd645779484724d579fc0d302bbaf146ff2 (diff)
downloadcpio-a3987da2a573bd2438f15df6faa680922025be18.tar.gz
cpio-a3987da2a573bd2438f15df6faa680922025be18.tar.bz2
Improve documentation.
* .gitignore: Update. * NEWS: Update. * doc/cpio.1: Rewrite. * doc/cpio.texi: Major revamp. * src/main.c (options): Fix sectioning of the help output. (parse_opt): * src/util.c: Use PAXEXIT_FAILURE to indicate an error.
-rw-r--r--.gitignore2
-rw-r--r--NEWS4
-rw-r--r--doc/cpio.1340
-rw-r--r--doc/cpio.texi546
-rw-r--r--src/main.c44
-rw-r--r--src/util.c4
6 files changed, 763 insertions, 177 deletions
diff --git a/.gitignore b/.gitignore
index ea5bcba..f1bcbd1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -25,7 +25,9 @@ config.status
configure
core
gnu
+gnulib
lib
m4
+paxutils
rmt
stamp-h1
diff --git a/NEWS b/NEWS
index ecb3c37..a7d2a57 100644
--- a/NEWS
+++ b/NEWS
@@ -1,4 +1,4 @@
-GNU cpio NEWS -- history of user-visible changes. 2014-01-28
+GNU cpio NEWS -- history of user-visible changes. 2014-01-30
Copyright (C) 2003, 2004, 2005, 2006, 2007, 2009,
2010, 2014 Free Software Foundation, Inc.
See the end of file for copying conditions.
@@ -7,6 +7,8 @@ Please send cpio bug reports to <bug-cpio@gnu.org>.
Version 2.11.90 - Git
+* Improved documentation.
+* Manpages are installed by make install.
Version 2.11 - Sergey Poznyakoff, 2010-03-10
diff --git a/doc/cpio.1 b/doc/cpio.1
index a3d81ca..53f9395 100644
--- a/doc/cpio.1
+++ b/doc/cpio.1
@@ -13,44 +13,324 @@
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with GNU cpio. If not, see <http://www.gnu.org/licenses/>.
-.TH CPIO 1 "January 28, 2014" "CPIO" "GNU CPIO"
+.TH CPIO 1 "January 29, 2014" "CPIO" "GNU CPIO"
.SH NAME
cpio \- copy files to and from archives
.SH SYNOPSIS
.B cpio
-{\-o|\-\-create} [\-0acvABLV] [\-C bytes] [\-H format] [\-M message]
-[\-O [[user@]host:]archive] [\-F [[user@]host:]archive]
-[\-\-file=[[user@]host:]archive] [\-\-format=format] [\-\-message=message]
-[\-\-null] [\-\-reset-access-time] [\-\-verbose] [\-\-dot] [\-\-append]
-[\-\-block-size=blocks] [\-\-dereference] [\-\-io-size=bytes] [\-\-quiet]
-[\-\-force\-local] [\-\-rsh-command=command] [\-\-help] [\-\-version]
-< name-list [> archive]
+{\fB\-o\fR|\fB\-\-create\fR} [\fB\-0acvABLV\fR] [\fB\-C\fR \fIBYTES\fR]
+[\fB\-H\fR \fIFORMAT\fR] [\fB\-M\fR \fIMESSAGE\fR]
+[\fB\-O\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
+[\fB\-F\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
+[\fB\-\-file=\fR[[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
+[\fB\-\-format=\fIFORMAT\fR] [\fB\-\-message=\fIMESSAGE\fR]
+[\fB\-\-null\fR] [\fB\-\-reset\-access\-time\fR] [\fB\-\-verbose\fR]
+[\fB\-\-dot\fR] [\fB\-\-append\fR]
+[\fB\-\-block\-size=\fIblocks\fR] [\fB\-\-dereference\fR]
+[\fB\-\-io\-size=\fIBYTES\fR] [\fB\-\-quiet\fR]
+[\fB\-\-force\-local\fR] [\fB\-\-rsh\-command=\fICOMMAND\fR]
+< \fIname-list\fR [\fB>\fR \fIarchive\fR]
.B cpio
-{\-i|\-\-extract} [\-bcdfmnrtsuvBSV] [\-C bytes] [\-E file] [\-H format]
-[\-M message] [\-R [user][:.][group]] [\-I [[user@]host:]archive]
-[\-F [[user@]host:]archive] [\-\-file=[[user@]host:]archive]
-[\-\-make-directories] [\-\-nonmatching] [\-\-preserve-modification-time]
-[\-\-numeric-uid-gid] [\-\-rename] [\-t|\-\-list] [\-\-swap-bytes] [\-\-swap] [\-\-dot]
-[\-\-unconditional] [\-\-verbose] [\-\-block-size=blocks] [\-\-swap-halfwords]
-[\-\-io-size=bytes] [\-\-pattern-file=file] [\-\-format=format]
-[\-\-owner=[user][:.][group]] [\-\-no-preserve-owner] [\-\-message=message]
-[\-\-force\-local] [\-\-no\-absolute\-filenames] [\-\-sparse]
-[\-\-only\-verify\-crc] [\-\-to\-stdout] [\-\-quiet] [\-\-rsh-command=command]
-[\-\-help] [\-\-version] [pattern...] [< archive]
+{\fB\-i\fR|\fB\-\-extract\fR} [\fB\-bcdfmnrtsuvBSV\fR] [\fB\-C\fR \fIBYTES\fR]
+[\fB\-E\fR \fIFILE\fR] [\fB\-H\fR \fIFORMAT\fR]
+[\fB\-M\fR \fIMESSAGE\fR] [\fB\-R\fR [\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]]
+[\fB\-I\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
+[\fB\-F\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
+[\fB\-\-file=\fR[[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
+[\fB\-\-make\-directories\fR] [\fB\-\-nonmatching\fR]
+[\fB\-\-preserve\-modification\-time\fR] [\fB\-\-numeric\-uid\-gid\fR]
+[\fB\-\-rename\fR] [\fB\-\-list\fR] [\fB\-\-swap\-bytes\fR]
+[\fB\-\-swap\fR] [\fB\-\-dot\fR] [\fB\-\-unconditional\fR]
+[\fB\-\-verbose\fR] [\fB\-\-block\-size=\fIBLOCKS\fR]
+[\fB\-\-swap\-halfwords\fR] [\fB\-\-io\-size=\fIBYTES\fR]
+[\fB\-\-pattern\-file=\fIFILE\fR] [\fB\-\-format=\fIFORMAT\fR]
+[\fB\-\-owner=\fR[\fIUSER][\fB:.\fR][\fIGROUP\fR]]
+[\fB\-\-no\-preserve\-owner\fR] [\fB\-\-message=\fIMESSAGE\fR]
+[\fB\-\-force\-local\fR] [\fB\-\-no\-absolute\-filenames\fR] [\fB\-\-sparse\fR]
+[\fB\-\-only\-verify\-crc\fR] [\fB\-\-to\-stdout\fR] [\fB\-\-quiet\fR]
+[\fB\-\-rsh\-command=\fICOMMAND\fR]
+[\fIpattern\fR...] [\fB<\fR \fIarchive\fR]
.B cpio
-{\-p|\-\-pass-through} [\-0adlmuvLV] [\-R [user][:.][group]]
-[\-\-null] [\-\-reset-access-time] [\-\-make-directories] [\-\-link] [\-\-quiet]
-[\-\-preserve-modification-time] [\-\-unconditional] [\-\-verbose] [\-\-dot]
-[\-\-dereference] [\-\-owner=[user][:.][group]] [\-\-no-preserve-owner]
-[\-\-sparse] [\-\-help] [\-\-version] destination-directory < name-list
-.SH DESCRIPTION
-GNU cpio is fully documented in the texinfo documentation. To access the
-help from your command line, type
+{\fB\-p\fR|\fB\-\-pass\-through\fR} [\fB\-0adlmuvLV\fR]
+[\fB\-R\fR [\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]]
+[\fB\-\-null\fR] [\fB\-\-reset\-access\-time\fR]
+[\fB\-\-make\-directories\fR] [\fB\-\-link\fR] [\fB\-\-quiet\fR]
+[\fB\-\-preserve\-modification\-time] [\fB\-\-unconditional\fR]
+[\fB\-\-verbose\fR] [\fB\-\-dot\fR] [\fB\-\-dereference\fR]
+[\fB\-\-owner=\fR[\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]]
+[\fB\-\-no\-preserve\-owner\fR] [\fB\-\-sparse\fR]
+\fIdestination-directory\fR \fB<\fR \fIname-list\fR
+
+.B cpio
+{\fB\-?\fR|\fB\-\-help\fR|\fB\-\-usage\fR|\fB\-\-version\fR}
+.SH NOTE
+This manpage is a short description of GNU \fBcpio\fR. For a detailed
+discussion, including examples and usage recommendations, refer to the
+\fBGNU Cpio Manual\fR available in texinfo format. If the \fBinfo\fR
+reader and the cpio documentation are properly installed on your
+system, the command
.PP
-\fBinfo cpio
+.RS +4
+.B info cpio
+.RE
.PP
-The online copy of the documentation is available at the following address:
+should give you access to the complete manual.
.PP
-http://www.gnu.org/software/cpio/manual
+You can also view the manual using the info mode in
+.BR emacs (1),
+or find it in various formats online at
+.PP
+.RS +4
+.B http://www.gnu.org/software/cpio/manual
+.RE
+.PP
+If any discrepancies occur between this manpage and the
+\fBGNU Cpio Manual\fR, the later shall be considered the authoritative
+source.
+.SH DESCRIPTION
+GNU \fBcpio\fR copies files between archives and directories. It
+supports the following archive formats: old binary cpio, old portable
+cpio, SVR4 cpio with and without checksum, HP cpio, and various tar
+formats.
+.PP
+The operation mode is requested by one of the following options:
+.TP
+.BR \-o ", " \-\-create
+Copy-out. Read a list of file names from the standard input and
+create on the standard output (unless overridden by the \fB\-\-file\fR
+option) an archive containing these files.
+.TP
+.BR \-i ", " \-\-extract
+Copy-in. Read the archive from standard input (or from the file
+supplied with the \fB\-\-file\fR option) and extract files from it, or
+(if the \fB\-t\fR option is given) list its contents to the standard
+output. If one or more \fIpattern\fRs are supplied, read or list only
+files matching these patterns. The \fB\-t\fR option alone implies
+\fB\-i\fR.
+.TP
+.BR \-p ", " \-\-pass\-through
+Pass-through. Read a list of file names from the standard input and
+copy them to the specified directory.
+.TP
+.BR \-? ", " \-\-help
+Give a short help summary and exit.
+.TP
+.B \-\-usage
+Print a short usage message and exit.
+.TP
+.B \-\-version
+Print program version and exit.
+.SH OPTIONS
+.SS Operation modifiers valid in any mode
+.TP
+\fB\-\-block\-size=\FIBLOCK-SIZE\fR
+Set the I/O block size to \fIBLOCK-SIZE\fR * 512 bytes.
+.TP
+.B \-B
+Set the I/O block size to 5120 bytes.
+.TP
+.B \-c
+Use the old portable (ASCII) archive format. This is the same as
+\fB\-H odc\fR.
+.TP
+\fB\-C\fR, \fB\-\-io\-size=\fINUMBER\fR
+Set the I/O block size to the given \fINUMBER\fR of bytes.
+.TP
+\fB\-D\fR, \fB\-\-directory=\fIDIR\fR
+Change to directory \fIDIR\fR.
+.TP
+.B \-\-force\-local
+Archive file is local, even if its name contains colons.
+.TP
+\fB\-H\fR, \fB\-\-format=\fIFORMAT\fR
+Use given archive \fBFORMAT\fR. Valid formats are (the number in
+parentheses gives maximum size for individual archive member):
+.RS
+.TP
+.B bin
+The obsolete binary format. (2147483647 bytes)
+.TP
+.B odc
+The old (POSIX.1) portable format. (8589934591 bytes)
+.TP
+.B newc
+The new (SVR4) portable format, which supports file systems
+having more than 65536 i-nodes. (4294967295 bytes)
+.TP
+.B crc
+The new (SVR4) portable format with a checksum added.
+.TP
+.B tar
+The old tar format. (8589934591 bytes)
+.TP
+.B ustar
+The POSIX.1 tar format. Also recognizes GNU tar archives,
+which are similar but not identical. (8589934591 bytes)
+.TP
+.B hpbin
+The obsolete binary format used by HPUX's cpio (which stores
+device files differently).
+.TP
+.B hpodc
+The portable format used by HPUX's cpio (which stores device
+files differently).
+.RE
+.TP
+\fB\-R\fR, \fB\-\-owner=\fR[\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]
+In copy-in and copy-pass mode, set the ownership of all files created
+to the specified \fIUSER\fR and/or \fIGROUP\fR. In copy-out mode,
+store the supplied owner information in the archive.
+.TP
+.B \-\-quiet
+Do not print the number of blocks copied at the end of the run.
+.TP
+.BI \-\-rsh\-command= COMMAND
+Use remote \fICOMMAND\fR instead of \fBrsh\fR.
+.TP
+.BR \-v ", " \-\-verbose
+Verbosely list the files processed.
+.TP
+.BR \-V ", " \-\-dot
+Print a "\fB.\fR" for each file processed.
+.TP
+\fB\-W\fR, \fB\-\-warning=\fIFLAG\fR
+Controlsи warning display. The \fIFLAG\fR is one of
+.BR none ,
+to disable all warnings,
+.BR all
+to enable them,
+.BR truncate ,
+to enable warnings about field truncation, and
+.BR no\-truncate ,
+to disable them.
+
+Multiple \fB\-W\fR options accumulate.
+.SS Operation modifiers valid in copy-in and copy-out modes
+.TP
+\fB\-F\fR, \fB\-\-file=\fR[[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE-FILE\fR
+Use this \fIARCHIVE-FILE\fR instead of standard input (in copy-in
+mode) or standard output (in copy-out mode). Optional \fIUSER\fR and
+\fIHOST\fR specify the user and host names in case of a remote
+archive.
+.TP
+\fB\-M\fR, \fB\-\-message=\fISTRING\fR
+Print \fISTRING\fR when the end of a volume of the backup media is reached.
+.SS Operation modifiers valid only in copy-in mode
+.TP
+.BR \-b ", " \-\-swap
+Swap both halfwords of words and bytes of halfwords in the data.
+Equivalent to \fB\-sS\fR.
+.TP
+.BR \-f ", " \-\-nonmatching
+Only copy files that do not match any of the given patterns.
+.TP
+.BR \-n ", " \-\-numeric\-uid\-gid
+In the verbose table of contents listing, show numeric UID and GID.
+.\" FIXME: special meaning when storing tar files.
+.TP
+.BR \-r ", " \-\-rename
+Interactively rename files.
+.TP
+.BR \-s ", " \-\-swap\-bytes
+Swap the bytes of each halfword in the files.
+.TP
+.BR \-S ", " \-\-swap\-halfwords
+Swap the halfwords of each word (4 bytes) in the files.
+.TP
+.B \-\-to\-stdout
+Extract files to standard output.
+.TP
+\fB\-E\fR, \fB\-\-pattern\-file=\fIFILE\fR
+Read additional patterns specifying filenames to extract or list from
+\fIFILE\fR.
+.TP
+.B \-\-only\-verify\-crc
+When reading a CRC format archive, only verify the CRC's of each file
+in the archive, without actually extracting the files.
+.SS Operation modifiers valid only in copy-out mode
+.TP
+.BR \-A ", " \-\-append
+Append to an existing archive.
+.TP
+\fB\-O\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE-NAME\fR
+Use \fIARCHIVE-NAME\fR instead of standard output. Optional \fIUSER\fR and
+\fIHOST\fR specify the user and host names in case of a remote
+archive.
+
+The output archive name can be specified wither using this option, or
+using \fB\-F\fR (\fB\-\-file\fR), but not both.
+.SS Operation modifiers valid only in copy-pass mode
+.TP
+.BR \-l ", " \-\-link
+Link files instead of copying them, when possible.
+.SS Operation modifiers valid in copy-in and copy-out modes
+.TP
+.B \-\-absolute\-filenames
+Do not strip file system prefix components from the file names.
+.TP
+.B \-\-no\-absolute\-filenames
+Create all files relative to the current directory.
+.SS Operation modifiers valid in copy-out and copy-pass modes
+.TP
+.BR \-0 ", " \-\-null
+Filenames in the list are delimited by null characters instead of
+newlines.
+.TP
+.BR \-a ", " \-\-reset\-access\-time
+Reset the access times of files after reading them.
+.TP
+\fB\-I\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE-NAME\fR
+Use \fIARCHIVE-NAME\fR instead of standard input. Optional \fIUSER\fR and
+\fIHOST\fR specify the user and host names in case of a remote
+archive.
+
+The input archive name can be specified wither using this option, or
+using \fB\-F\fR (\fB\-\-file\fR), but not both.
+.TP
+.BR \-L ", " \-\-dereference
+Dereference symbolic links (copy the files that they point to instead
+of copying the links).
+.SS Operation modifiers valid in copy-in and copy-pass modes
+.TP
+.BR \-d ", " \-\-make\-directories
+Create leading directories where needed.
+.TP
+.BR \-m ", " \-\-preserve\-modification\-time
+Retain previous file modification times when creating files.
+.TP
+.B \-\-no\-preserve\-owner
+Do not change the ownership of the files.
+.TP
+.B \-\-sparse
+Write files with large blocks of zeros as sparse files.
+.TP
+.BR \-u ", " \-\-unconditional
+Replace all files unconditionally.
+.SH "RETURN VALUE"
+GNU \fBcpio\fR exits with code \fB0\fR if it was able to successfully
+complete the requested operation. On errors, it exits with code \fB2\fR.
+.SH "SEE ALSO"
+.BR tar (1),
+.BR rmt (8),
+.BR mt (1).
+.SH "BUG REPORTS"
+Report bugs to <bug\-cpio@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2014 Free Software Foundation, Inc.
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
+
diff --git a/doc/cpio.texi b/doc/cpio.texi
index bcece3c..5a739ab 100644
--- a/doc/cpio.texi
+++ b/doc/cpio.texi
@@ -35,7 +35,7 @@ Software Foundation raise funds for GNU development.''
@titlepage
@title GNU CPIO
@subtitle @value{VERSION} @value{UPDATED}
-@author by Robert Carleton
+@author by Robert Carleton and Sergey Poznyakoff
@c copyright page
@page
@vskip 0pt plus 1filll
@@ -46,18 +46,18 @@ Published by the Free Software Foundation @*
Boston, MA 02110-1301, USA @*
@end titlepage
-@node Top, Introduction, (dir), (dir)
-@comment node-name, next, previous, up
+@ifnottex
+@node Top
+@top GNU CPIO
+@insertcopying
@ifinfo
-@top
-
GNU cpio is a tool for creating and extracting archives, or copying
files from one place to another. It handles a number of cpio formats as
well as reading and writing tar files. This is the first edition of the
GNU cpio documentation and is consistent with @value{VERSION}.
-
@end ifinfo
+@end ifnottex
@menu
* Introduction::
@@ -80,8 +80,7 @@ Invoking cpio
@end detailmenu
@end menu
-@node Introduction, Tutorial, Top, Top
-@comment node-name, next, previous, up
+@node Introduction
@chapter Introduction
GNU cpio copies files into or out of a cpio or tar archive, The archive
@@ -89,14 +88,13 @@ can be another file on the disk, a magnetic tape, or a pipe.
GNU cpio supports the following archive formats: binary, old ASCII, new
ASCII, crc, HPUX binary, HPUX old ASCII, old tar, and POSIX.1 tar. The
-tar format is provided for compatibility with the tar program. By
+tar format is provided for compatibility with the @command{tar} program. By
default, cpio creates binary format archives, for compatibility with
older cpio programs. When extracting from archives, cpio automatically
recognizes which kind of archive it is reading and can read archives
created on machines with a different byte-order.
-@node Tutorial, Invoking cpio, Introduction, Top
-@comment node-name, next, previous, up
+@node Tutorial
@chapter Tutorial
@cindex creating a cpio archive
@cindex extracting a cpio archive
@@ -206,8 +204,7 @@ file names between find and cpio, even if special characters are
embedded in the file names. Another is @option{-p}, which tells cpio to
pass the files it finds to the directory @samp{new-dir}.
-@node Invoking cpio, Media, Tutorial, Top
-@comment node-name, next, previous, up
+@node Invoking cpio
@chapter Invoking cpio
@cindex invoking cpio
@cindex command line options
@@ -219,132 +216,397 @@ pass the files it finds to the directory @samp{new-dir}.
* Options::
@end menu
-@node Copy-out mode, Copy-in mode, Invoking cpio, Invoking cpio
-@comment node-name, next, previous, up
+@node Copy-out mode
@section Copy-out mode
-
+@anchor{copy-out}
+@cindex copy-out
+@cindex archive creation
+@cindex create archive
In copy-out mode, cpio copies files into an archive. It reads a list
of filenames, one per line, on the standard input, and writes the
archive onto the standard output. A typical way to generate the list
-of filenames is with the find command; you should give find the -depth
-option to minimize problems with permissions on directories that are
-unreadable.
-@xref{Options}.
+of filenames is with the find command; you should give @command{find}
+the @option{-depth} option to minimize problems with permissions on
+directories that are unreadable.
+
+Copy-out mode is requested by the @option{-o} (@option{--create})
+command line option, e.g.:
@example
-cpio @{-o|--create@} [-0acvABLV] [-C bytes] [-H format]
-[-M message] [-O [[user@@]host:]archive] [-F [[user@@]host:]archive]
-[--file=[[user@@]host:]archive] [--format=format]
-[--message=message] [--null] [--reset-access-time] [--verbose]
-[--dot] [--append] [--block-size=blocks] [--dereference]
-[--io-size=bytes] [--rsh-command=command] [--help] [--version]
-< name-list [> archive]
+@cartouche
+% find | cpio -o > directory.cpio
+@end cartouche
@end example
-@node Copy-in mode, Copy-pass mode, Copy-out mode, Invoking cpio
-@comment node-name, next, previous, up
-@section Copy-in mode
+The following options can be used in copy-out mode:
-In copy-in mode, cpio copies files out of an archive or lists the
-archive contents. It reads the archive from the standard input. Any
-non-option command line arguments are shell globbing patterns; only
-files in the archive whose names match one or more of those patterns are
-copied from the archive. Unlike in the shell, an initial @samp{.} in a
-filename does match a wildcard at the start of a pattern, and a @samp{/} in a
-filename can match wildcards. If no patterns are given, all files are
-extracted. @xref{Options}.
+@table @option
+@item -0
+@itemx --null
+Filenames in the list are delimited by ASCII null characters instead
+of newlines.
+@item -A
+@itemx --append
+Append to an existing archive.
+@item -a
+@itemx --reset-access-time
+Reset the access times of files after reading them.
+@item --absolute-filenames
+Do not strip file system prefix components from the file names.
+@item --no-absolute-filenames
+Strip file system prefix components from the file names before storing
+them to the archive.
+@item --block-size=@var{block-size}
+Sets the I/O block size to @var{block-size} * 512 bytes.
+@item -B
+Set the I/O block size to 5120 bytes.
+@item -c
+Use the old portable (ASCII) archive format.
+@item -C @var{number}
+@itemx --io-size=@var{number}
+Set the I/O block size to the given @var{number} of bytes.
+@item -D @var{dir}
+@itemx --directory=@var{dir}
+Change to directory @var{dir}
+@item --force-local
+Treat the archive file as local, even if its name contains colons.
+@item -F [[@var{user}@@]@var{host}:]@var{archive-file}
+@itemx -O [[@var{user}@@]@var{host}:]@var{archive-file}
+@itemx --file=[[@var{user}@@]@var{host}:]@var{archive-file}
+Use the supplied @var{archive-file} instead of standard input.
+Optional @var{user} and @var{host} specify the user and host names in
+case of a remote archive.
+@item -H @var{format}
+@itemx --format=@var{format}
+Use given archive format. @xref{format}, for a list of available
+formats.
+@item -L
+@itemx --dereference
+Dereference symbolic links (copy the files that they point to instead
+of copying the links).
+@item -M @var{string}
+@itemx --message=@var{string}
+Print @var{string} when the end of a volume of the backup media is
+reached.
+@item --quiet
+Do not print the number of blocks copied.
+@item --rsh-command=@var{command}
+Use @var{command} instead of @command{rsh} to access remote archives.
+@item -R
+@itemx --owner=[@var{user}][:.][@var{group}]
+Set the ownership of all files created to the specified @var{user}
+and/or @var{group}.
+@item -v
+@itemx --verbose
+Verbosely list the files processed.
+@item -V
+@itemx --dot
+Print a @samp{.} for each file processed.
+@item -W
+@item --warning=@var{flag}
+Control warning display. Argument is one of @samp{none},
+@samp{truncate}, @samp{no-truncate} or @samp{all}. @xref{warning},
+for a detailed discussion of these.
+@end table
-@example
-cpio @{-i|--extract@} [-bcdfmnrtsuvBSV] [-C bytes] [-E file]
-[-H format] [-M message] [-R [user][:.][group]]
-[-I [[user@@]host:]archive] [-F [[user@@]host:]archive]
-[--file=[[user@@]host:]archive] [--make-directories]
-[--nonmatching] [--preserve-modification-time]
-[--numeric-uid-gid] [--rename] [--list] [--swap-bytes] [--swap]
-[--dot] [--unconditional] [--verbose] [--block-size=blocks]
-[--swap-halfwords] [--io-size=bytes] [--pattern-file=file]
-[--format=format] [--owner=[user][:.][group]]
-[--no-preserve-owner] [--message=message] [--help] [--version]
-[--no-absolute-filenames] [--sparse] [-only-verify-crc] [--to-stdout]
-[-quiet] [--rsh-command=command] [pattern...] [< archive]
-@end example
+@node Copy-in mode
+@section Copy-in mode
+@anchor{copy-in}
+@cindex copy-in
+@cindex archive extraction
+@cindex extract files from an archive
+In copy-in mode, cpio copies files from an archive into the filesystem
+or lists the archive contents. It reads the archive from the standard
+input. Any non-option command line arguments are shell globbing
+patterns; only files in the archive whose names match one or more of
+those patterns are copied from the archive. Unlike in the shell, an
+initial @samp{.} in a filename does match a wildcard at the start of a
+pattern, and a @samp{/} in a filename can match wildcards. If no
+patterns are given, all files are extracted.
+
+The copy-in mode is requested by the @option{-i} (@option{--extract})
+command line option.
+
+The following options can be used in copy-in mode:
+
+@table @option
+@item --absolute-filenames
+Do not strip file system prefix components from the file names.
+@item --no-absolute-filenames
+Create all files relative to the current directory.
+@item --block-size=@var{block-size}
+Sets the I/O block size to @var{block-size} * 512 bytes.
+@item -b
+@itemx --swap
+Swap both halfwords of words and bytes of halfwords in the data.
+Equivalent to @option{-sS}.
+@item -B
+Set the I/O block size to 5120 bytes.
+@item -c
+Use the old portable (ASCII) archive format.
+@item -C @var{number}
+@itemx --io-size=@var{number}
+Set the I/O block size to the given @var{number} of bytes.
+@item -D @var{dir}
+@itemx --directory=@var{dir}
+Change to directory @var{dir}
+@item -d
+@itemx --make-directories
+Create leading directories where needed.
+@item -E @var{file}
+@itemx --pattern-file=@var{file}
+Read additional patterns specifying filenames to extract or list from
+@var{file}.
+@item -f
+@itemx --nonmatching
+Only copy files that do not match any of the given patterns.
+@item --force-local
+Treat the archive file as local, even if its name contains colons.
+@item -F [[@var{user}@@]@var{host}:]@var{archive-file}
+@itemx -I [[@var{user}@@]@var{host}:]@var{archive-file}
+@itemx --file=[[@var{user}@@]@var{host}:]@var{archive-file}
+Use the supplied @var{archive-file} instead of standard input.
+Optional @var{user} and @var{host} specify the user and host names in
+case of a remote archive.
+@item -H @var{format}
+@itemx --format=@var{format}
+Use given archive format. @xref{format}, for a list of available
+formats.
+@item -m
+@itemx --preserve-modification-time
+Retain previous file modification times when creating files.
+@item -M @var{string}
+@itemx --message=@var{string}
+Print @var{string} when the end of a volume of the backup media is
+reached.
+@item --no-preserve-owner
+Do not change the ownership of the files.
+@item -n
+@itemx --numeric-uid-gid
+In the verbose table of contents listing, show numeric UID and GID values.
+@item --only-verify-crc
+When reading a CRC format archive, only verify the CRC's of each file
+in the archive, don't actually extract the files
+@item --quiet
+Do not print the number of blocks copied.
+@item --rsh-command=@var{command}
+Use @var{command} instead of @command{rsh} to access remote archives.
+@item -r
+@itemx --rename
+Interactively rename files
+@item --sparse
+Write files with large blocks of zeros as sparse files.
+@item -s
+@itemx --swap-bytes
+Swap the bytes of each halfword in the files
+@item -S
+@itemx --swap-halfwords
+Swap the halfwords of each word (4 bytes) in the files
+@item --to-stdout
+Extract files to standard output.
+@item -u
+@itemx --unconditional
+Replace all files unconditionally.
+@item -v
+@itemx --verbose
+Verbosely list the files processed.
+@item -V
+@itemx --dot
+Print a @samp{.} for each file processed.
+@item -W
+@item --warning=@var{flag}
+Control warning display. Argument is one of @samp{none},
+@samp{truncate}, @samp{no-truncate} or @samp{all}. @xref{warning},
+for a detailed discussion of these.
+@end table
-@node Copy-pass mode, Options, Copy-in mode, Invoking cpio
-@comment node-name, next, previous, up
+@node Copy-pass mode
@section Copy-pass mode
+@anchor{copy-pass}
+@cindex copy-pass
+@cindex copy files between filesystems
In copy-pass mode, cpio copies files from one directory tree to
another, combining the copy-out and copy-in steps without actually
using an archive. It reads the list of files to copy from the
standard input; the directory into which it will copy them is given as
a non-option argument.
-@xref{Options}.
-@example
-cpio @{-p|--pass-through@} [-0adlmuvLV] [-R [user][:.][group]]
-[--null] [--reset-access-time] [--make-directories] [--link]
-[--preserve-modification-time] [--unconditional] [--verbose]
-[--dot] [--dereference] [--owner=[user][:.][group]] [--sparse]
-[--no-preserve-owner] [--help] [--version] destination-directory
-< name-list
-@end example
+This mode is requested by the @option{-p} (@option{--pass-through})
+command line option.
+The following options are valid in copy-out mode:
+@table @option
+@item -0
+@itemx --null
+Filenames in the list are delimited by ASCII null characters instead
+of newlines.
+@item -a
+@itemx --reset-access-time
+Reset the access times of files after reading them.
+@item -b
+@itemx --swap
+Swap both halfwords of words and bytes of halfwords in the data.
+Equivalent to @option{-sS}.
+@item --block-size=@var{block-size}
+Sets the I/O block size to @var{block-size} * 512 bytes.
+@item -B
+Set the I/O block size to 5120 bytes.
+@item -c
+Use the old portable (ASCII) archive format.
+@item -C @var{number}
+@itemx --io-size=@var{number}
+Set the I/O block size to the given @var{number} of bytes.
+@item -d
+@itemx --make-directories
+Create leading directories where needed.
+@item -D @var{dir}
+@itemx --directory=@var{dir}
+Change to directory @var{dir}
+@item -E @var{file}
+@itemx --pattern-file=@var{file}
+Read additional patterns specifying filenames to extract or list from
+@var{file}.
+@item -f
+@itemx --nonmatching
+Only copy files that do not match any of the given patterns.
+@item -F [[@var{user}@@]@var{host}:]@var{archive-file}
+@item -O [[@var{user}@@]@var{host}:]@var{archive-file}
+@itemx --file=[[@var{user}@@]@var{host}:]@var{archive-file}
+Use the supplied @var{archive-file} instead of standard input.
+Optional @var{user} and @var{host} specify the user and host names in
+case of a remote archive.
+@item --force-local
+Treat the archive file as local, even if its name contains colons.
+@item -H @var{format}
+@itemx --format=@var{format}
+Use given archive format. @xref{format}, for a list of available
+formats.
+@item -l
+@itemx --link
+Link files instead of copying them, when possible.
+@item -L
+@itemx --dereference
+Dereference symbolic links (copy the files that they point to instead
+of copying the links).
+@item -m
+@itemx --preserve-modification-time
+Retain previous file modification times when creating files.
+@item -M @var{string}
+@itemx --message=@var{string}
+Print @var{string} when the end of a volume of the backup media is
+reached.
+@item -n
+@itemx --numeric-uid-gid
+In the verbose table of contents listing, show numeric UID and GID values.
+@item --no-preserve-owner
+Do not change the ownership of the files.
+@item --only-verify-crc
+When reading a CRC format archive, only verify the CRC's of each file
+in the archive, don't actually extract the files
+@item --quiet
+Do not print the number of blocks copied.
+@item --rsh-command=@var{command}
+Use @var{command} instead of @command{rsh} to access remote archives.
+@item -r
+@itemx --rename
+Interactively rename files
+@item -R
+@itemx --owner=[@var{user}][:.][@var{group}]
+Set the ownership of all files created to the specified @var{user}
+and/or @var{group}.
+@item -s
+@itemx --swap-bytes
+Swap the bytes of each halfword in the files
+@item --sparse
+Write files with large blocks of zeros as sparse files.
+@item -S
+@itemx --swap-halfwords
+Swap the halfwords of each word (4 bytes) in the files
+@item --to-stdout
+Extract files to standard output.
+@item -u
+@itemx --unconditional
+Replace all files unconditionally.
+@item -v
+@itemx --verbose
+Verbosely list the files processed.
+@item -V
+@itemx --dot
+Print a @samp{.} for each file processed.
+@item -W
+@item --warning=@var{flag}
+Control warning display. Argument is one of @samp{none},
+@samp{truncate}, @samp{no-truncate} or @samp{all}. @xref{warning},
+for a detailed discussion of these.
+@end table
-@node Options, , Copy-pass mode, Invoking cpio
-@comment node-name, next, previous, up
+
+@node Options
@section Options
+This section summarizes all available command line options. References
+in square brackets after each option indicate @command{cpio} modes in
+which this option is valid.
@table @code
-
-
@item -0
@itemx --null
-Read a list of filenames terminated by a null character, instead of a
+[@ref{copy-in},@ref{copy-out},@ref{copy-pass}]
+@*Read a list of filenames terminated by a null character, instead of a
newline, so that files whose names contain newlines can be archived.
GNU find is one way to produce a list of null-terminated filenames.
This option may be used in copy-out and copy-pass modes.
@item -a
@itemx --reset-access-time
-Reset the access times of files after reading them, so
+[@ref{copy-out},@ref{copy-pass}]
+@*Reset the access times of files after reading them, so
that it does not look like they have just been read.
@item -A
@itemx --append
-Append to an existing archive. Only works in copy-out
+[@ref{copy-out}]
+@*Append to an existing archive. Only works in copy-out
mode. The archive must be a disk file specified with
the @option{-O} or @option{-F} (@option{--file}) option.
@item -b
@itemx --swap
-Swap both halfwords of words and bytes of halfwords in the data.
-Equivalent to -sS. This option may be used in copy-in mode. Use this
+[@ref{copy-in}]
+@*Swap both halfwords of words and bytes of halfwords in the data.
+Equivalent to @option{-sS}. This option may be used in copy-in mode. Use this
option to convert 32-bit integers between big-endian and little-endian
machines.
-@item -B
-Set the I/O block size to 5120 bytes. Initially the
+@item -B
+[@ref{copy-in},@ref{copy-out},@ref{copy-pass}]
+@*Set the I/O block size to 5120 bytes. Initially the
block size is 512 bytes.
@item --block-size=@var{block-size}
-Set the I/O block size to @var{block-size} * 512 bytes.
+[@ref{copy-in},@ref{copy-out},@ref{copy-pass}]
+@*Set the I/O block size to @var{block-size} * 512 bytes.
@item -c
-Use the old portable (ASCII) archive format.
+[@ref{copy-in},@ref{copy-out},@ref{copy-pass}]
+@*Use the old portable (ASCII) archive format.
@item -C @var{io-size}
@itemx --io-size=@var{io-size}
-Set the I/O block size to @var{io-size} bytes.
+[@ref{copy-in},@ref{copy-out},@ref{copy-pass}]
+@*Set the I/O block size to @var{io-size} bytes.
@item -d
@itemx --make-directories
-Create leading directories where needed.
+[@ref{copy-in},@ref{copy-pass}]
+@*Create leading directories where needed.
@item -D @var{dir}
-@item --directory=@var{dir}
-Change to the directory @var{dir} before starting the operation. This
+@itemx --directory=@var{dir}
+[@ref{copy-in},@ref{copy-out},@ref{copy-pass}]
+@*Change to the directory @var{dir} before starting the operation. This
can be used, for example, to extract an archive contents in a
different directory:
@@ -376,18 +638,21 @@ the current working directory, then change to the directory
@item -E @var{file}
@itemx --pattern-file=@var{file}
-Read additional patterns specifying filenames to extract or list from
+[@ref{copy-in}]
+@*Read additional patterns specifying filenames to extract or list from
@var{file}. The lines of @var{file} are treated as if they had been non-option
arguments to cpio. This option is used in copy-in mode,
@item -f
@itemx --nonmatching
-Only copy files that do not match any of the given
+[@ref{copy-in}]
+@*Only copy files that do not match any of the given
patterns.
@item -F @var{archive}
@itemx --file=@var{archive}
-Archive filename to use instead of standard input or output. To use a
+[@ref{copy-in},@ref{copy-out}]
+@*Archive filename to use instead of standard input or output. To use a
tape drive on another machine as the archive, use a filename that starts
with @samp{@var{hostname}:}, where @var{hostname} is the name or IP
address of the machine. The hostname can be preceded by a username and an
@@ -396,13 +661,16 @@ permission to do so (typically an entry in that user's @file{~/.rhosts}
file).
@item --force-local
-With @option{-F}, @option{-I}, or @option{-O}, take the archive file name to be a
-local file even if it contains a colon, which would
+[@ref{copy-in},@ref{copy-out}]
+@*With @option{-F}, @option{-I}, or @option{-O}, take the archive file
+name to be a local file even if it contains a colon, which would
ordinarily indicate a remote host name.
+@anchor{format}
@item -H @var{format}
@itemx --format=@var{format}
-Use archive format @var{format}. The valid formats are listed below
+[@ref{copy-in},@ref{copy-out},@ref{copy-pass}]
+@*Use archive format @var{format}. The valid formats are listed below
with file size limits for individual files in parentheses; the same
names are also recognized in all-caps. The default in copy-in mode is
to automatically detect the archive format, and in copy-out mode is
@@ -444,47 +712,53