cpio/man/downstream.patch

--- man/latest-output	2015-09-14 13:51:18.454800210 +0200
+++ cpio.1	2015-09-14 13:51:48.741061959 +0200
@@ -1,11 +1,103 @@
-.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.1.
-.TH CPIO "1" "September 2015" "cpio 2.12" "User Commands"
+.\" DO NOT MODIFY THIS FILE!  It was (partly) generated by help2man from
+.\" cpio --help/cpio --version output and partly patched by downstream
+.\" package maintainers.
+.TH CPIO 1L \" -*- nroff -*-
 .SH NAME
-cpio \- manual page for cpio 2.12
+cpio \- copy files to and from archives
+.SH __WARNING__
+.PP
+The cpio utility is considered LEGACY based on POSIX specification.  Users are
+encouraged to use other archiving tools for archive creation.
+
+If you decided to use cpio, you should almost always force cpio to use the
+ustar format in copy-out mode by the -H option (cpio -o -H ustar).  This is
+because the ustar format is well defined in POSIX specification and thus
+readable by wide range of other archiving tools (including tar e.g.).
+
+By default, GNU cpio uses (for historical reasons) the very old binary format
+('bin') which has significant problems nowadays, e.g. with storing big inode
+numbers (see the Red Hat bug #952313).
+
+Note also that these days the modern 'pax' archive format should be considered
+as the default -- but this format is not implemented in GNU cpio.  You should,
+again, consider using other archivers (e.g. 'tar --format=pax').
+
 .SH SYNOPSIS
+\&\fBCopy-out mode\fR
+.PP
+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.  see \*(lqOptions\*(rq.
+.PP
+.B cpio
+{\-o|\-\-create} [\-0acvABLV] [\-C bytes] [\-H format] [\-D DIR]
+[\-M message] [\-O [[user@]host:]archive] [\-F [[user@]host:]archive]
+[\-\-file=[[user@]host:]archive] [\-\-format=format] [\-\-warning=FLAG]
+[\-\-message=message][\-\-null] [\-\-reset\-access\-time] [\-\-verbose]
+[\-\-dot] [\-\-append] [\-\-block\-size=blocks] [\-\-dereference]
+[\-\-io\-size=bytes] [\-\-rsh\-command=command]  [\-\-license] [\-\-usage]
+[\-\-help] [\-\-version]
+< name-list [> archive]
+.PP
+\&\fBCopy-in mode\fR
+.PP
+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 `\fB.\fR' in a
+filename does match a wildcard at the start of a pattern, and a `\fB/\fR' in a
+filename can match wildcards.  If no patterns are given, all files are
+extracted.  see \*(lqOptions\*(rq.
+.PP
 .B cpio
-[\fI\,OPTION\/\fR...] [\fI\,destination-directory\/\fR]
+{\-i|\-\-extract} [\-bcdfmnrtsuvBSV] [\-C bytes] [\-E file] [\-H format]
+[\-D DIR]
+[\-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] [\-\-warning=FLAG] [\-\-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] [\-\-absolute\-filenames]
+[\-\-sparse] [\-\-only\-verify\-crc] [\-\-to\-stdout] [\-\-quiet]
+[\-\-ignore\-devno] [\-\-renumber\-inodes] [\-\-device\-independent]
+[\-\-reproducible]
+[\-\-rsh-command=command] [\-\-license] [\-\-usage] [\-\-help]
+[\-\-version] [pattern...] [< archive]
+.PP
+\&\fBCopy-pass mode\fR
+.PP
+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.  see \*(lqOptions\*(rq.
+.PP
+.B cpio
+{\-p|\-\-pass-through} [\-0adlmuvLV] [\-R [user][:.][group]] [\-D DIR]
+[\-\-null] [\-\-reset-access-time] [\-\-make-directories] [\-\-link] [\-\-quiet]
+[\-\-preserve-modification-time] [\-\-unconditional] [\-\-verbose] [\-\-dot]
+[\-\-warning=FLAG] [\-\-dereference] [\-\-owner=[user][:.][group]]
+[\-\-no-preserve-owner] [\-\-sparse]  [\-\-license] [\-\-usage] [\-\-help]
+[\-\-version] destination-directory < name-list
+.PP
 .SH DESCRIPTION
+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.
+.PP
+Following archive formats are supported: 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
+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.
+.PP
 .SS "Main operation mode:"
 .TP
 \fB\-i\fR, \fB\-\-extract\fR
@@ -27,7 +119,8 @@
 bytes
 .TP
 \fB\-B\fR
-Set the I/O block size to 5120 bytes
+Set the I/O block size to 5120 bytes.
+Initially the block size is 512 bytes.
 .TP
 \fB\-c\fR
 Identical to "\-H newc", use the new (SVR4)
@@ -42,21 +135,61 @@
 Change to directory DIR
 .TP
 \fB\-\-force\-local\fR
-Archive file is local, even if its name contains
-colons
+With \-F, \-I, or \-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.
 .TP
 \fB\-H\fR, \fB\-\-format\fR=\fI\,FORMAT\/\fR
-Use given archive FORMAT
+Use given archive FORMAT.
+The valid formats are listed below; 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 `\fBbin\fR'.
+.TP
+`bin'
+The obsolete binary format.
+.TP
+`odc'
+The old (\s-1POSIX\s0.1) portable format.
+.TP
+`newc'
+The new (\s-1SVR4\s0) portable format, which supports file systems
+having more than 65536 i\-nodes.
+.TP
+`crc'
+The new (\s-1SVR4\s0) portable format with a checksum (Sum32) added.
+.TP
+`tar'
+The old tar format.
+.TP
+`ustar'
+The \s-1POSIX\s0.1 tar format.  Also recognizes \s-1GNU\s0 tar archives,
+which are similar but not identical.
+.TP
+`hpbin'
+The obsolete binary format used by \s-1HPUX\s0's cpio (which stores
+device files differently).
+.TP
+`hpodc'
+The portable format used by \s-1HPUX\s0's cpio (which stores device
+files differently).
 .TP
 \fB\-\-quiet\fR
 Do not print the number of blocks copied
 .TP
 \fB\-R\fR, \fB\-\-owner\fR=\fI\,[USER][\/\fR:.][GROUP]
 Set the ownership of all files created to the
-specified USER and/or GROUP
+specified USER and/or GROUP.
+Either the user, the group, or both, must be present.  If the group is omitted
+but the \&\*(lq:\*(rq or \*(lq.\*(rq separator is given, use the given user's
+login group.  Only the super-user can change files' ownership in copy\-in mode.
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
-Verbosely list the files processed
+List the files processed, or with `\fB\-t\fR', give an `\fBls \-l\fR' style
+table of contents listing.  In a verbose table of contents of a
+ustar archive, user and group names in the archive that do not
+exist on the local system are replaced by the names that
+correspond locally to the numeric \s-1UID\s0 and \s-1GID\s0 stored in the
+archive.
 .TP
 \fB\-V\fR, \fB\-\-dot\fR
 Print a "." for each file processed
@@ -73,22 +206,28 @@
 and host names in case of a remote archive
 .TP
 \fB\-M\fR, \fB\-\-message\fR=\fI\,STRING\/\fR
-Print STRING when the end of a volume of the
-backup media is reached
+Print \s-1STRING\s0 when the end of a volume of the backup media (such
+as a tape or a floppy disk) is reached, to prompt the user to
+insert a new volume.  If \s-1STRING\s0 contains the string \*(lq%d\*(rq, it is
+replaced by the current volume number (starting at 1).
 .TP
 \fB\-\-rsh\-command\fR=\fI\,COMMAND\/\fR
 Use COMMAND instead of rsh
+(typically /usr/bin/ssh)
 .SS "Operation modifiers valid only in copy-in mode:"
 .TP
 \fB\-b\fR, \fB\-\-swap\fR
 Swap both halfwords of words and bytes of
 halfwords in the data. Equivalent to \fB\-sS\fR
+Use this option to convert 32\-bit integers between big-endian and little-endian
+machines.
 .TP
 \fB\-f\fR, \fB\-\-nonmatching\fR
 Only copy files that do not match any of the given
 patterns
 .TP
-\fB\-I\fR [[USER@]HOST:]FILE\-NAME Archive filename to use instead of standard input.
+\fB\-I\fR [[USER@]HOST:]FILE\-NAME
+Archive filename to use instead of standard input.
 Optional USER and HOST specify the user and host
 names in case of a remote archive
 .TP
@@ -121,6 +260,7 @@
 .TP
 \fB\-A\fR, \fB\-\-append\fR
 Append to an existing archive.
+The archive must be a disk file specified with the \-O or \-F (\-file) option.
 .TP
 \fB\-\-device\-independent\fR, \fB\-\-reproducible\fR
 Create device\-independent (reproducible) archives
@@ -128,7 +268,8 @@
 \fB\-\-ignore\-devno\fR
 Don't store device numbers
 .TP
-\fB\-O\fR [[USER@]HOST:]FILE\-NAME Archive filename to use instead of standard
+\fB\-O\fR [[USER@]HOST:]FILE\-NAME
+Archive filename to use instead of standard
 output. Optional USER and HOST specify the user
 and host names in case of a remote archive
 .TP
@@ -152,10 +293,13 @@
 .TP
 \fB\-0\fR, \fB\-\-null\fR
 Filenames in the list are delimited by null
-characters instead of newlines
+characters instead of newlines, so that files whose names contain newlines can
+be archived.  \s-1GNU\s0 find is one way to produce a list of null-terminated
+filenames.
 .TP
 \fB\-a\fR, \fB\-\-reset\-access\-time\fR
-Reset the access times of files after reading them
+Reset the access times of files after reading them, so that it
+does not look like they have just been read.
 .TP
 \fB\-L\fR, \fB\-\-dereference\fR
 Dereference  symbolic  links  (copy  the files
@@ -170,7 +314,10 @@
 creating files
 .TP
 \fB\-\-no\-preserve\-owner\fR
-Do not change the ownership of the files
+Do not change the ownership of the files; leave them owned by the
+user extracting them.  This is the default for non-root users, so
+that users on System V don't inadvertently give away files.  This
+option can be used in copy-in mode and copy-pass mode
 .TP
 \fB\-\-sparse\fR
 Write files with large blocks of zeros as sparse
@@ -190,11 +337,83 @@
 .PP
 Mandatory or optional arguments to long options are also mandatory or optional
 for any corresponding short options.
+
+.PP
+.SH EXAMPLES
+When creating an archive, cpio takes the list of files to be
+processed from the standard input, and then sends the archive to the
+standard output, or to the device defined by the `\fB\-F\fR' option.
+Usually find or ls is used to provide this list to
+the standard input.  In the following example you can see the
+possibilities for archiving the contents of a single directory.
+.PP
+.B % ls | cpio \-ov > directory.cpio
+.PP
+The `\fB\-o\fR' option creates the archive, and the `\fB\-v\fR' option prints the
+names of the files archived as they are added.  Notice that the options
+can be put together after a single `\fB\-\fR' or can be placed separately on
+the command line.  The `\fB>\fR' redirects the cpio output to the file
+`\fBdirectory.cpio\fR'.
+.PP
+If you wanted to archive an entire directory tree, the find command
+can provide the file list to cpio:
+.PP
+.B % find . \-print \-depth | cpio \-ov > tree.cpio
+.PP
+This will take all the files in the current directory, the
+directories below and place them in the archive tree.cpio.  Again the
+`\fB\-o\fR' creates an archive, and the `\fB\-v\fR' option shows you the name of the
+files as they are archived.  see \*(lqCopy\-out mode\*(rq.  Using the `\fB.\fR' in
+the find statement will give you more flexibility when doing restores,
+as it will save file names with a relative path vice a hard wired,
+absolute path.  The `\fB\-depth\fR' option forces `\fBfind\fR' to print of the
+entries in a directory before printing the directory itself.  This
+limits the effects of restrictive directory permissions by printing the
+directory entries in a directory before the directory name itself.
+.PP
+Extracting an archive requires a bit more thought because cpio will
+not create directories by default.  Another characteristic, is it will
+not overwrite existing files unless you tell it to.
+.PP
+.B % cpio \-iv < directory.cpio
+.PP
+This will retrieve the files archived in the file directory.cpio and
+place them in the present directory.  The `\fB\-i\fR' option extracts the
+archive and the `\fB\-v\fR' shows the file names as they are extracted.  If
+you are dealing with an archived directory tree, you need to use the
+`\fB\-d\fR' option to create directories as necessary, something like:
+.PP
+.B % cpio \-idv < tree.cpio
+.PP
+This will take the contents of the archive tree.cpio and extract it
+to the current directory.  If you try to extract the files on top of
+files of the same name that already exist (and have the same or later
+modification time) cpio will not extract the file unless told to do so
+by the \-u option.  see \*(lqCopy\-in mode\*(rq.
+.PP
+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.  see \*(lqCopy\-pass mode\*(rq.
+.PP
+.B % find . \-depth \-print0 | cpio \-\-null \-pvd new-dir
+.PP
+The example shows copying the files of the present directory, and
+sub-directories to a new directory called new\-dir.  Some new options are
+the `\fB\-print0\fR' available with \s-1GNU\s0 find, combined with the `\fB\-\-null\fR'
+option of cpio.  These two options act together to send file names
+between find and cpio, even if special characters are embedded in the
+file names.  Another is `\fB\-p\fR', which tells cpio to pass the files it
+finds to the directory `\fBnew-dir\fR'.
+
+
 .SH AUTHOR
 Written by Phil Nelson, David MacKenzie, John Oleynick,
 and Sergey Poznyakoff.
 .SH "REPORTING BUGS"
 Report bugs to <bug\-cpio@gnu.org>.
+Report bugs in this manual page via https://bugzilla.redhat.com.
 .SH COPYRIGHT
 Copyright \(co 2015 Free Software Foundation, Inc.
 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
@@ -213,3 +432,7 @@
 .B info cpio
 .PP
 should give you access to the complete manual.
+
+The online copy of the documentation is available at the following address:
+.PP
+http://www.gnu.org/software/cpio/manual