358 lines
15 KiB
Diff
358 lines
15 KiB
Diff
--- 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
|