.TH GCPIO 1
.SH NAME
cpio \- copy files to and from archives
.SH SYNOPSIS
.B cpio
{\-o|+create} [\-0acvBLOV] [+null] [+reset-access-time] [+binary]
[+portability] [+verbose] [+block-size=blocks] [+dereference]
[\-F [[user@]host:]archive] [+file=[[user@]host:]archive] [+version]
< name-list [> archive]

.B cpio
{-i|+extract} [\-cdfmnrtuvBOV] [+binary] [+portability]
[+make-directories] [+nonmatching] [+preserve-modification-time]
[+numeric-uid-gid] [+rename] [+list] [+unconditional] [+verbose]
[\-F [[user@]host:]archive] [+file=[[user@]host:]archive]
[+block-size=blocks] [+version] [pattern...] [< archive]

.B cpio
{-p|+pass-through} [\-0adlLmuvV] [+null] [+reset-access-time]
[+make-directories] [+link] [+preserve-modification-time]
[+unconditional] [+verbose] [+dereference] [+version]
destination-directory < name-list
.SH DESCRIPTION
This manual page
documents the GNU version of
.BR cpio .
.B cpio
copies files into or out of a cpio archive, which is a file that
contains other files plus information about them, such as their
pathname, owner, timestamps, and access permissions.  The archive can
be another file on the disk, a magnetic tape, or a pipe.
.B cpio
has three operating modes.
.PP
In copy-out mode,
.B 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.
.PP
In copy-in mode,
.B 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 `.' in a filename does
match a wildcard at the start of a pattern, and a `/' in a filename
can match wildcards.  If no patterns are given, all files are
extracted.
.PP
In copy-pass mode,
.B 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.
.PP
Two cpio archive formats exist: binary and ASCII.  The binary format
is obsolete because it encodes information about the files in a way
that is not portable between different machine architectures.
However,
.B cpio
recognizes which kind of archive it is reading automatically and can
read archives created on machines with a different byte-order.
By default, it creates binary format archives, for compatibility with
older
.B cpio
programs.
.PP
Some of the options to
.B cpio
apply only to certain operating modes; see the SYNOPSIS section for a
list of which options are allowed in which modes.
.SS OPTIONS
.TP
.I "\-0, +null"
In copy-out and copy-pass modes, 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
.B find
is one way to produce a list of null-terminated filenames.
.TP
.I "\-a, +reset-access-time"
Reset the access times of files after reading them, so that it does
not look like they have just been read.
.TP
.I "\-B"
Set the I/O block size to 5120 bytes.  Initially the block size is 512
bytes.
.TP
.I "+block-size=BLOCK-SIZE"
Set the I/O block size to BLOCK-SIZE bytes.
.TP
.I "\-c, +portability"
Use the portable (ASCII) archive format.
.TP
.I "\-d, +make-directories"
Create leading directories where needed.
.TP
.I "\-f, +nonmatching"
Only copy files that do not match any of the given patterns.
.TP
.I "\-F, +file=archive"
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 `HOSTNAME:/dev/'.  The hostname can be preceded by a
username and an `@' to access the remote tape drive as that user, if
you have permission to do so (typically an entry in that user's
`~/.rhosts' file).
.TP
.I "\-i, +extract"
Run in copy-in mode.
.TP
.I "\-l, +link"
Link files instead of copying them, when possible.
.TP
.I "\-L, +dereference"
Dereference symbolic links (copy the files that they point to instead
of copying the links).
.TP
.I "\-m, +preserve-modification-time"
Retain previous file modification times when creating files.
.TP
.I "\-n, +numeric-uid-gid"
In the verbose table of contents listing, show numeric UID and GID
instead of translating them into names.
.TP
.I "\-o, +create"
Run in copy-out mode.
.TP
.I "\-O, +binary"
Use the old endian-dependent (binary) archive format.
.TP
.I "\-p, +pass-through"
Run in copy-pass mode.
.TP
.I "\-r, +rename"
Interactively rename files.
.TP
.I "\-t, +list"
Print a table of contents of the input.
.TP
.I "\-u, +unconditional"
Replace all files, without asking whether to replace existing newer
files with older files.
.TP
.I "\-v, +verbose"
List the files processed, or give an `ls \-l' style table of contents
listing.
.TP
.I "\-V, +version"
Print the cpio program version and exit.