You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
438 lines
16 KiB
438 lines
16 KiB
.\" 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 \- 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 |
|
{\-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 |
|
Extract files from an archive (run in copy\-in |
|
mode) |
|
.TP |
|
\fB\-o\fR, \fB\-\-create\fR |
|
Create the archive (run in copy\-out mode) |
|
.TP |
|
\fB\-p\fR, \fB\-\-pass\-through\fR |
|
Run in copy\-pass mode |
|
.TP |
|
\fB\-t\fR, \fB\-\-list\fR |
|
Print a table of contents of the input |
|
.SS "Operation modifiers valid in any mode:" |
|
.TP |
|
\fB\-\-block\-size\fR=\fI\,BLOCK\-SIZE\/\fR |
|
Set the I/O block size to BLOCK\-SIZE * 512 |
|
bytes |
|
.TP |
|
\fB\-B\fR |
|
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) |
|
portable format. If you wish the old portable |
|
(ASCII) archive format, use "\-H odc" instead. |
|
.TP |
|
\fB\-C\fR, \fB\-\-io\-size\fR=\fI\,NUMBER\/\fR |
|
Set the I/O block size to the given NUMBER of |
|
bytes |
|
.TP |
|
\fB\-D\fR, \fB\-\-directory\fR=\fI\,DIR\/\fR |
|
Change to directory DIR |
|
.TP |
|
\fB\-\-force\-local\fR |
|
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. |
|
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. |
|
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 |
|
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 |
|
.TP |
|
\fB\-W\fR, \fB\-\-warning\fR=\fI\,FLAG\/\fR |
|
Control warning display. Currently FLAG is one of |
|
\&'none', 'truncate', 'all'. Multiple options |
|
accumulate. |
|
.SS "Operation modifiers valid in copy-in and copy-out modes:" |
|
.TP |
|
\fB\-F\fR, \fB\-\-file\fR=\fI\,[[USER\/\fR@]HOST:]FILE\-NAME |
|
Use this FILE\-NAME instead of standard input or |
|
output. Optional USER and HOST specify the user |
|
and host names in case of a remote archive |
|
.TP |
|
\fB\-M\fR, \fB\-\-message\fR=\fI\,STRING\/\fR |
|
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. |
|
Optional USER and HOST specify the user and host |
|
names in case of a remote archive |
|
.TP |
|
\fB\-n\fR, \fB\-\-numeric\-uid\-gid\fR |
|
In the verbose table of contents listing, show |
|
numeric UID and GID |
|
.TP |
|
\fB\-r\fR, \fB\-\-rename\fR |
|
Interactively rename files |
|
.TP |
|
\fB\-s\fR, \fB\-\-swap\-bytes\fR |
|
Swap the bytes of each halfword in the files |
|
.TP |
|
\fB\-S\fR, \fB\-\-swap\-halfwords\fR |
|
Swap the halfwords of each word (4 bytes) in the |
|
files |
|
.TP |
|
\fB\-\-to\-stdout\fR |
|
Extract files to standard output |
|
.TP |
|
\fB\-E\fR, \fB\-\-pattern\-file\fR=\fI\,FILE\/\fR |
|
Read additional patterns specifying filenames to |
|
extract or list from FILE |
|
.TP |
|
\fB\-\-only\-verify\-crc\fR |
|
When reading a CRC format archive, only verify the |
|
checksum of each file in the archive, don't |
|
actually extract the files |
|
.SS "Operation modifiers valid only in copy-out mode:" |
|
.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 |
|
.TP |
|
\fB\-\-ignore\-devno\fR |
|
Don't store device numbers |
|
.TP |
|
\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 |
|
\fB\-\-renumber\-inodes\fR |
|
Renumber inodes |
|
.SS "Operation modifiers valid only in copy-pass mode:" |
|
.TP |
|
\fB\-l\fR, \fB\-\-link\fR |
|
Link files instead of copying them, when |
|
possible |
|
.SS "Operation modifiers valid in copy-in and copy-out modes:" |
|
.TP |
|
\fB\-\-absolute\-filenames\fR |
|
Do not strip file system prefix components from |
|
the file names |
|
.TP |
|
\fB\-\-no\-absolute\-filenames\fR |
|
Create all files relative to the current |
|
directory |
|
.SS "Operation modifiers valid in copy-out and copy-pass modes:" |
|
.TP |
|
\fB\-0\fR, \fB\-\-null\fR |
|
Filenames in the list are delimited by null |
|
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, 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 |
|
that they point to instead of copying the links). |
|
.SS "Operation modifiers valid in copy-in and copy-pass modes:" |
|
.TP |
|
\fB\-d\fR, \fB\-\-make\-directories\fR |
|
Create leading directories where needed |
|
.TP |
|
\fB\-m\fR, \fB\-\-preserve\-modification\-time\fR |
|
Retain previous file modification times when |
|
creating files |
|
.TP |
|
\fB\-\-no\-preserve\-owner\fR |
|
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 |
|
files |
|
.TP |
|
\fB\-u\fR, \fB\-\-unconditional\fR |
|
Replace all files unconditionally |
|
.TP |
|
\-?, \fB\-\-help\fR |
|
give this help list |
|
.TP |
|
\fB\-\-usage\fR |
|
give a short usage message |
|
.TP |
|
\fB\-\-version\fR |
|
print program version |
|
.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>. |
|
.br |
|
This is free software: you are free to change and redistribute it. |
|
There is NO WARRANTY, to the extent permitted by law. |
|
.SH "SEE ALSO" |
|
The full documentation for |
|
.B cpio |
|
is maintained as a Texinfo manual. If the |
|
.B info |
|
and |
|
.B cpio |
|
programs are properly installed at your site, the command |
|
.IP |
|
.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
|
|
|