Blame SOURCES/cpio.1

6af787
.\" DO NOT MODIFY THIS FILE!  It was (partly) generated by help2man from
6af787
.\" cpio --help/cpio --version output and partly patched by downstream
6af787
.\" package maintainers.
6af787
.TH CPIO 1L \" -*- nroff -*-
6af787
.SH NAME
6af787
cpio \- copy files to and from archives
6af787
.SH __WARNING__
6af787
.PP
6af787
The cpio utility is considered LEGACY based on POSIX specification.  Users are
6af787
encouraged to use other archiving tools for archive creation.
6af787
6af787
If you decided to use cpio, you should almost always force cpio to use the
6af787
ustar format in copy-out mode by the -H option (cpio -o -H ustar).  This is
6af787
because the ustar format is well defined in POSIX specification and thus
6af787
readable by wide range of other archiving tools (including tar e.g.).
6af787
6af787
By default, GNU cpio uses (for historical reasons) the very old binary format
6af787
('bin') which has significant problems nowadays, e.g. with storing big inode
6af787
numbers (see the Red Hat bug #952313).
6af787
6af787
Note also that these days the modern 'pax' archive format should be considered
6af787
as the default -- but this format is not implemented in GNU cpio.  You should,
6af787
again, consider using other archivers (e.g. 'tar --format=pax').
6af787
6af787
.SH SYNOPSIS
6af787
\&\fBCopy-out mode\fR
6af787
.PP
6af787
In copy-out mode, cpio copies files into an archive.  It reads a list
6af787
of filenames, one per line, on the standard input, and writes the
6af787
archive onto the standard output.  A typical way to generate the list
6af787
of filenames is with the find command; you should give find the \-depth
6af787
option to minimize problems with permissions on directories that are
6af787
unreadable.  see \*(lqOptions\*(rq.
6af787
.PP
6af787
.B cpio
6af787
{\-o|\-\-create} [\-0acvABLV] [\-C bytes] [\-H format] [\-D DIR]
6af787
[\-M message] [\-O [[user@]host:]archive] [\-F [[user@]host:]archive]
6af787
[\-\-file=[[user@]host:]archive] [\-\-format=format] [\-\-warning=FLAG]
6af787
[\-\-message=message][\-\-null] [\-\-reset\-access\-time] [\-\-verbose]
6af787
[\-\-dot] [\-\-append] [\-\-block\-size=blocks] [\-\-dereference]
6af787
[\-\-io\-size=bytes] [\-\-rsh\-command=command]  [\-\-license] [\-\-usage]
6af787
[\-\-help] [\-\-version]
6af787
< name-list [> archive]
6af787
.PP
6af787
\&\fBCopy-in mode\fR
6af787
.PP
6af787
In copy-in mode, cpio copies files out of an archive or lists the
6af787
archive contents.  It reads the archive from the standard input.  Any
6af787
non-option command line arguments are shell globbing patterns; only
6af787
files in the archive whose names match one or more of those patterns are
6af787
copied from the archive.  Unlike in the shell, an initial `\fB.\fR' in a
6af787
filename does match a wildcard at the start of a pattern, and a `\fB/\fR' in a
6af787
filename can match wildcards.  If no patterns are given, all files are
6af787
extracted.  see \*(lqOptions\*(rq.
6af787
.PP
6af787
.B cpio
6af787
{\-i|\-\-extract} [\-bcdfmnrtsuvBSV] [\-C bytes] [\-E file] [\-H format]
6af787
[\-D DIR]
6af787
[\-M message] [\-R [user][:.][group]] [\-I [[user@]host:]archive]
6af787
[\-F [[user@]host:]archive] [\-\-file=[[user@]host:]archive]
6af787
[\-\-make-directories] [\-\-nonmatching] [\-\-preserve-modification-time]
6af787
[\-\-numeric-uid-gid] [\-\-rename] [\-t|\-\-list] [\-\-swap-bytes] [\-\-swap]
6af787
[\-\-dot] [\-\-warning=FLAG] [\-\-unconditional] [\-\-verbose]
6af787
[\-\-block-size=blocks] [\-\-swap-halfwords] [\-\-io-size=bytes]
6af787
[\-\-pattern-file=file] [\-\-format=format] [\-\-owner=[user][:.][group]]
6af787
[\-\-no-preserve-owner] [\-\-message=message]
6af787
[\-\-force\-local] [\-\-no\-absolute\-filenames] [\-\-absolute\-filenames]
6af787
[\-\-sparse] [\-\-only\-verify\-crc] [\-\-to\-stdout] [\-\-quiet]
6af787
[\-\-ignore\-devno] [\-\-renumber\-inodes] [\-\-device\-independent]
6af787
[\-\-reproducible]
6af787
[\-\-rsh-command=command] [\-\-license] [\-\-usage] [\-\-help]
6af787
[\-\-version] [pattern...] [< archive]
6af787
.PP
6af787
\&\fBCopy-pass mode\fR
6af787
.PP
6af787
In copy-pass mode, cpio copies files from one directory tree to
6af787
another, combining the copy-out and copy-in steps without actually
6af787
using an archive.  It reads the list of files to copy from the standard
6af787
input; the directory into which it will copy them is given as a
6af787
non-option argument.  see \*(lqOptions\*(rq.
6af787
.PP
6af787
.B cpio
6af787
{\-p|\-\-pass-through} [\-0adlmuvLV] [\-R [user][:.][group]] [\-D DIR]
6af787
[\-\-null] [\-\-reset-access-time] [\-\-make-directories] [\-\-link] [\-\-quiet]
6af787
[\-\-preserve-modification-time] [\-\-unconditional] [\-\-verbose] [\-\-dot]
6af787
[\-\-warning=FLAG] [\-\-dereference] [\-\-owner=[user][:.][group]]
6af787
[\-\-no-preserve-owner] [\-\-sparse]  [\-\-license] [\-\-usage] [\-\-help]
6af787
[\-\-version] destination-directory < name-list
6af787
.PP
6af787
.SH DESCRIPTION
6af787
GNU cpio is a tool for creating and extracting archives, or copying
6af787
files from one place to another.  It handles a number of cpio formats as
6af787
well as reading and writing tar files.
6af787
.PP
6af787
Following archive formats are supported: binary, old ASCII, new ASCII, crc, HPUX binary, HPUX old
6af787
ASCII, old tar, and POSIX.1 tar.  The tar format is provided for compatibility with the tar program. By
6af787
default, cpio creates binary format archives, for compatibility with older cpio programs.  When extracting
6af787
from archives, cpio automatically recognizes which kind of archive it is reading and can read archives created 
6af787
on machines with a different byte-order.
6af787
.PP
6af787
.SS "Main operation mode:"
6af787
.TP
6af787
\fB\-i\fR, \fB\-\-extract\fR
6af787
Extract files from an archive (run in copy\-in
6af787
mode)
6af787
.TP
6af787
\fB\-o\fR, \fB\-\-create\fR
6af787
Create the archive (run in copy\-out mode)
6af787
.TP
6af787
\fB\-p\fR, \fB\-\-pass\-through\fR
6af787
Run in copy\-pass mode
6af787
.TP
6af787
\fB\-t\fR, \fB\-\-list\fR
6af787
Print a table of contents of the input
6af787
.SS "Operation modifiers valid in any mode:"
6af787
.TP
6af787
\fB\-\-block\-size\fR=\fI\,BLOCK\-SIZE\/\fR
6af787
Set the I/O block size to BLOCK\-SIZE * 512
6af787
bytes
6af787
.TP
6af787
\fB\-B\fR
6af787
Set the I/O block size to 5120 bytes.
6af787
Initially the block size is 512 bytes.
6af787
.TP
6af787
\fB\-c\fR
6af787
Identical to "\-H newc", use the new (SVR4)
6af787
portable format. If you wish the old portable
6af787
(ASCII) archive format, use "\-H odc" instead.
6af787
.TP
6af787
\fB\-C\fR, \fB\-\-io\-size\fR=\fI\,NUMBER\/\fR
6af787
Set the I/O block size to the given NUMBER of
6af787
bytes
6af787
.TP
6af787
\fB\-D\fR, \fB\-\-directory\fR=\fI\,DIR\/\fR
6af787
Change to directory DIR
6af787
.TP
6af787
\fB\-\-force\-local\fR
6af787
With \-F, \-I, or \-O, take the archive file name to be a local file
6af787
even if it contains a colon, which would ordinarily indicate a
6af787
remote host name.
6af787
.TP
6af787
\fB\-H\fR, \fB\-\-format\fR=\fI\,FORMAT\/\fR
6af787
Use given archive FORMAT.
6af787
The valid formats are listed below; the same names are also recognized in
6af787
all\-caps.  The default in copy-in mode is to automatically detect the archive
6af787
format, and in copy-out mode is `\fBbin\fR'.
6af787
.TP
6af787
`bin'
6af787
The obsolete binary format.
6af787
.TP
6af787
`odc'
6af787
The old (\s-1POSIX\s0.1) portable format.
6af787
.TP
6af787
`newc'
6af787
The new (\s-1SVR4\s0) portable format, which supports file systems
6af787
having more than 65536 i\-nodes.
6af787
.TP
6af787
`crc'
6af787
The new (\s-1SVR4\s0) portable format with a checksum (Sum32) added.
6af787
.TP
6af787
`tar'
6af787
The old tar format.
6af787
.TP
6af787
`ustar'
6af787
The \s-1POSIX\s0.1 tar format.  Also recognizes \s-1GNU\s0 tar archives,
6af787
which are similar but not identical.
6af787
.TP
6af787
`hpbin'
6af787
The obsolete binary format used by \s-1HPUX\s0's cpio (which stores
6af787
device files differently).
6af787
.TP
6af787
`hpodc'
6af787
The portable format used by \s-1HPUX\s0's cpio (which stores device
6af787
files differently).
6af787
.TP
6af787
\fB\-\-quiet\fR
6af787
Do not print the number of blocks copied
6af787
.TP
6af787
\fB\-R\fR, \fB\-\-owner\fR=\fI\,[USER][\/\fR:.][GROUP]
6af787
Set the ownership of all files created to the
6af787
specified USER and/or GROUP.
6af787
Either the user, the group, or both, must be present.  If the group is omitted
6af787
but the \&\*(lq:\*(rq or \*(lq.\*(rq separator is given, use the given user's
6af787
login group.  Only the super-user can change files' ownership in copy\-in mode.
6af787
.TP
6af787
\fB\-v\fR, \fB\-\-verbose\fR
6af787
List the files processed, or with `\fB\-t\fR', give an `\fBls \-l\fR' style
6af787
table of contents listing.  In a verbose table of contents of a
6af787
ustar archive, user and group names in the archive that do not
6af787
exist on the local system are replaced by the names that
6af787
correspond locally to the numeric \s-1UID\s0 and \s-1GID\s0 stored in the
6af787
archive.
6af787
.TP
6af787
\fB\-V\fR, \fB\-\-dot\fR
6af787
Print a "." for each file processed
6af787
.TP
6af787
\fB\-W\fR, \fB\-\-warning\fR=\fI\,FLAG\/\fR
6af787
Control warning display. Currently FLAG is one of
6af787
\&'none', 'truncate', 'all'. Multiple options
6af787
accumulate.
6af787
.SS "Operation modifiers valid in copy-in and copy-out modes:"
6af787
.TP
6af787
\fB\-F\fR, \fB\-\-file\fR=\fI\,[[USER\/\fR@]HOST:]FILE\-NAME
6af787
Use this FILE\-NAME instead of standard input or
6af787
output. Optional USER and HOST specify the user
6af787
and host names in case of a remote archive
6af787
.TP
6af787
\fB\-M\fR, \fB\-\-message\fR=\fI\,STRING\/\fR
6af787
Print \s-1STRING\s0 when the end of a volume of the backup media (such
6af787
as a tape or a floppy disk) is reached, to prompt the user to
6af787
insert a new volume.  If \s-1STRING\s0 contains the string \*(lq%d\*(rq, it is
6af787
replaced by the current volume number (starting at 1).
6af787
.TP
6af787
\fB\-\-rsh\-command\fR=\fI\,COMMAND\/\fR
6af787
Use COMMAND instead of rsh
6af787
(typically /usr/bin/ssh)
6af787
.SS "Operation modifiers valid only in copy-in mode:"
6af787
.TP
6af787
\fB\-b\fR, \fB\-\-swap\fR
6af787
Swap both halfwords of words and bytes of
6af787
halfwords in the data. Equivalent to \fB\-sS\fR
6af787
Use this option to convert 32\-bit integers between big-endian and little-endian
6af787
machines.
6af787
.TP
6af787
\fB\-f\fR, \fB\-\-nonmatching\fR
6af787
Only copy files that do not match any of the given
6af787
patterns
6af787
.TP
6af787
\fB\-I\fR [[USER@]HOST:]FILE\-NAME
6af787
Archive filename to use instead of standard input.
6af787
Optional USER and HOST specify the user and host
6af787
names in case of a remote archive
6af787
.TP
6af787
\fB\-n\fR, \fB\-\-numeric\-uid\-gid\fR
6af787
In the verbose table of contents listing, show
6af787
numeric UID and GID
6af787
.TP
6af787
\fB\-r\fR, \fB\-\-rename\fR
6af787
Interactively rename files
6af787
.TP
6af787
\fB\-s\fR, \fB\-\-swap\-bytes\fR
6af787
Swap the bytes of each halfword in the files
6af787
.TP
6af787
\fB\-S\fR, \fB\-\-swap\-halfwords\fR
6af787
Swap the halfwords of each word (4 bytes) in the
6af787
files
6af787
.TP
6af787
\fB\-\-to\-stdout\fR
6af787
Extract files to standard output
6af787
.TP
6af787
\fB\-E\fR, \fB\-\-pattern\-file\fR=\fI\,FILE\/\fR
6af787
Read additional patterns specifying filenames to
6af787
extract or list from FILE
6af787
.TP
6af787
\fB\-\-only\-verify\-crc\fR
6af787
When reading a CRC format archive, only verify the
6af787
checksum of each file in the archive, don't
6af787
actually extract the files
6af787
.SS "Operation modifiers valid only in copy-out mode:"
6af787
.TP
6af787
\fB\-A\fR, \fB\-\-append\fR
6af787
Append to an existing archive.
6af787
The archive must be a disk file specified with the \-O or \-F (\-file) option.
6af787
.TP
6af787
\fB\-\-device\-independent\fR, \fB\-\-reproducible\fR
6af787
Create device\-independent (reproducible) archives
6af787
.TP
6af787
\fB\-\-ignore\-devno\fR
6af787
Don't store device numbers
6af787
.TP
6af787
\fB\-O\fR [[USER@]HOST:]FILE\-NAME
6af787
Archive filename to use instead of standard
6af787
output. Optional USER and HOST specify the user
6af787
and host names in case of a remote archive
6af787
.TP
6af787
\fB\-\-renumber\-inodes\fR
6af787
Renumber inodes
6af787
.SS "Operation modifiers valid only in copy-pass mode:"
6af787
.TP
6af787
\fB\-l\fR, \fB\-\-link\fR
6af787
Link files instead of copying them, when
6af787
possible
6af787
.SS "Operation modifiers valid in copy-in and copy-out modes:"
6af787
.TP
6af787
\fB\-\-absolute\-filenames\fR
6af787
Do not strip file system prefix components from
6af787
the file names
6af787
.TP
6af787
\fB\-\-no\-absolute\-filenames\fR
6af787
Create all files relative to the current
6af787
directory
6af787
.SS "Operation modifiers valid in copy-out and copy-pass modes:"
6af787
.TP
6af787
\fB\-0\fR, \fB\-\-null\fR
6af787
Filenames in the list are delimited by null
6af787
characters instead of newlines, so that files whose names contain newlines can
6af787
be archived.  \s-1GNU\s0 find is one way to produce a list of null-terminated
6af787
filenames.
6af787
.TP
6af787
\fB\-a\fR, \fB\-\-reset\-access\-time\fR
6af787
Reset the access times of files after reading them, so that it
6af787
does not look like they have just been read.
6af787
.TP
6af787
\fB\-L\fR, \fB\-\-dereference\fR
6af787
Dereference  symbolic  links  (copy  the files
6af787
that they point to instead of copying the links).
6af787
.SS "Operation modifiers valid in copy-in and copy-pass modes:"
6af787
.TP
6af787
\fB\-d\fR, \fB\-\-make\-directories\fR
6af787
Create leading directories where needed
6af787
.TP
6af787
\fB\-m\fR, \fB\-\-preserve\-modification\-time\fR
6af787
Retain previous file modification times when
6af787
creating files
6af787
.TP
6af787
\fB\-\-no\-preserve\-owner\fR
6af787
Do not change the ownership of the files; leave them owned by the
6af787
user extracting them.  This is the default for non-root users, so
6af787
that users on System V don't inadvertently give away files.  This
6af787
option can be used in copy-in mode and copy-pass mode
6af787
.TP
6af787
\fB\-\-sparse\fR
6af787
Write files with large blocks of zeros as sparse
6af787
files
6af787
.TP
6af787
\fB\-u\fR, \fB\-\-unconditional\fR
6af787
Replace all files unconditionally
6af787
.TP
6af787
\-?, \fB\-\-help\fR
6af787
give this help list
6af787
.TP
6af787
\fB\-\-usage\fR
6af787
give a short usage message
6af787
.TP
6af787
\fB\-\-version\fR
6af787
print program version
6af787
.PP
6af787
Mandatory or optional arguments to long options are also mandatory or optional
6af787
for any corresponding short options.
6af787
6af787
.PP
6af787
.SH EXAMPLES
6af787
When creating an archive, cpio takes the list of files to be
6af787
processed from the standard input, and then sends the archive to the
6af787
standard output, or to the device defined by the `\fB\-F\fR' option.
6af787
Usually find or ls is used to provide this list to
6af787
the standard input.  In the following example you can see the
6af787
possibilities for archiving the contents of a single directory.
6af787
.PP
6af787
.B % ls | cpio \-ov > directory.cpio
6af787
.PP
6af787
The `\fB\-o\fR' option creates the archive, and the `\fB\-v\fR' option prints the
6af787
names of the files archived as they are added.  Notice that the options
6af787
can be put together after a single `\fB\-\fR' or can be placed separately on
6af787
the command line.  The `\fB>\fR' redirects the cpio output to the file
6af787
`\fBdirectory.cpio\fR'.
6af787
.PP
6af787
If you wanted to archive an entire directory tree, the find command
6af787
can provide the file list to cpio:
6af787
.PP
6af787
.B % find . \-print \-depth | cpio \-ov > tree.cpio
6af787
.PP
6af787
This will take all the files in the current directory, the
6af787
directories below and place them in the archive tree.cpio.  Again the
6af787
`\fB\-o\fR' creates an archive, and the `\fB\-v\fR' option shows you the name of the
6af787
files as they are archived.  see \*(lqCopy\-out mode\*(rq.  Using the `\fB.\fR' in
6af787
the find statement will give you more flexibility when doing restores,
6af787
as it will save file names with a relative path vice a hard wired,
6af787
absolute path.  The `\fB\-depth\fR' option forces `\fBfind\fR' to print of the
6af787
entries in a directory before printing the directory itself.  This
6af787
limits the effects of restrictive directory permissions by printing the
6af787
directory entries in a directory before the directory name itself.
6af787
.PP
6af787
Extracting an archive requires a bit more thought because cpio will
6af787
not create directories by default.  Another characteristic, is it will
6af787
not overwrite existing files unless you tell it to.
6af787
.PP
6af787
.B % cpio \-iv < directory.cpio
6af787
.PP
6af787
This will retrieve the files archived in the file directory.cpio and
6af787
place them in the present directory.  The `\fB\-i\fR' option extracts the
6af787
archive and the `\fB\-v\fR' shows the file names as they are extracted.  If
6af787
you are dealing with an archived directory tree, you need to use the
6af787
`\fB\-d\fR' option to create directories as necessary, something like:
6af787
.PP
6af787
.B % cpio \-idv < tree.cpio
6af787
.PP
6af787
This will take the contents of the archive tree.cpio and extract it
6af787
to the current directory.  If you try to extract the files on top of
6af787
files of the same name that already exist (and have the same or later
6af787
modification time) cpio will not extract the file unless told to do so
6af787
by the \-u option.  see \*(lqCopy\-in mode\*(rq.
6af787
.PP
6af787
In copy-pass mode, cpio copies files from one directory tree to
6af787
another, combining the copy-out and copy-in steps without actually
6af787
using an archive.  It reads the list of files to copy from the standard
6af787
input; the directory into which it will copy them is given as a
6af787
non-option argument.  see \*(lqCopy\-pass mode\*(rq.
6af787
.PP
6af787
.B % find . \-depth \-print0 | cpio \-\-null \-pvd new-dir
6af787
.PP
6af787
The example shows copying the files of the present directory, and
6af787
sub-directories to a new directory called new\-dir.  Some new options are
6af787
the `\fB\-print0\fR' available with \s-1GNU\s0 find, combined with the `\fB\-\-null\fR'
6af787
option of cpio.  These two options act together to send file names
6af787
between find and cpio, even if special characters are embedded in the
6af787
file names.  Another is `\fB\-p\fR', which tells cpio to pass the files it
6af787
finds to the directory `\fBnew-dir\fR'.
6af787
6af787
6af787
.SH AUTHOR
6af787
Written by Phil Nelson, David MacKenzie, John Oleynick,
6af787
and Sergey Poznyakoff.
6af787
.SH "REPORTING BUGS"
6af787
Report bugs to <bug\-cpio@gnu.org>.
6af787
Report bugs in this manual page via https://bugzilla.redhat.com.
6af787
.SH COPYRIGHT
6af787
Copyright \(co 2015 Free Software Foundation, Inc.
6af787
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
6af787
.br
6af787
This is free software: you are free to change and redistribute it.
6af787
There is NO WARRANTY, to the extent permitted by law.
6af787
.SH "SEE ALSO"
6af787
The full documentation for
6af787
.B cpio
6af787
is maintained as a Texinfo manual.  If the
6af787
.B info
6af787
and
6af787
.B cpio
6af787
programs are properly installed at your site, the command
6af787
.IP
6af787
.B info cpio
6af787
.PP
6af787
should give you access to the complete manual.
6af787
6af787
The online copy of the documentation is available at the following address:
6af787
.PP
6af787
http://www.gnu.org/software/cpio/manual