.TH gnucpio "" "" Command
.PC "Archiving/backup utility"
.na
.fi
\fICopy-in mode:\fR
\fBcpio
{-o|--create}
[\-0acvABLV]
[\-C \fIbytes\^\fB]
[\-H \fIformat\^\fB]
[\-M \fImessage\fB]
[\-O [[\fIuser\fB@]\fIhost\^\fB:]\fIarchive\^\fB]
[\-F [[\fIuser\fB@]\fIhost\^\fB:]\fIarchive\^\fB]\fR
[\-\-file=[[\fIuser\^\fB@]\fIhost\^\fB:]\fIarchive\^\fB]
[\-\-format=\fIformat\^\fB]
[\-\-message=\fImessage\^\fB]
[\-\-null]
[\-\-reset-access-time]
[\-\-verbose]
[\-\-dot]
[\-\-append]
[\-\-block-size=\^\fBblocks\^\fB]
[\-\-dereference]
[\-\-io-size=\fIbytes\^\fB]
[\-\-version]
< \fIname-list\fB
[> \fIarchive\^\fB]\fR
.sp \n(pDu
\fICopy-out mode:\fR
\fBcpio
{-i|--extract}
[\-bcdfmnrtsuvBSV]
[\-C \fIbytes\^\fB]
[\-E \fIfile\^\fB]
[\-H \fIformat\^\fB]
[\-M \fImessage\^\fB]
[\-R [\fIuser\^\fB][:.][\fIgroup\^\fB]]
[\-I [[\fIuser\^\fB@]\fIhost\^\fB:]\fIarchive\^\fB]
[\-F [[\fIuser\^\fB@]\fIhost\^\fB:]\fIarchive\^\fB]
[\-\-file=[[\fIuser\^\fB@]\fIhost\^\fB:]\fIarchive\^\fB]
[\-\-make-directories]
[\-\-nonmatching]
[\-\-preserve-modification-time]
[\-\-numeric-uid-gid]
[\-\-rename]
[\-\-list]
[\-\-swap-bytes]
[\-\-swap]
[\-\-dot]
[\-\-unconditional]
[\-\-verbose]
[\-\-block-size=\fIblocks\^\fB]
[\-\-swap-halfwords]
[\-\-io-size=\fIbytes\^\fB]
[\-\-pattern-file=\fIfile\^\fB]
[\-\-format=\fIformat\^\fB]
[\-\-owner=[\fIuser\^\fB][:.][\fIgroup\^\fB]]
[\-\-no-preserve-owner]
[\-\-message=\fImessage\^\fB]
[\-\-version]
[\fIpattern...\^\fB]
[< \fIarchive\^\fB]\fR
.sp \n(pDu
\fICopy-through mode:\fR
\fBcpio
{-p|--pass-through}
[\-0adlmuvLV]
[\-R [\fIuser\^\fB][:.][\fIgroup\^\fB]]
[\-\-null]
[\-\-reset-access-time]
[\-\-make-directories]
[\-\-link]
[\-\-preserve-modification-time]
[\-\-unconditional]
[\-\-verbose]
[\-\-dot]
[\-\-dereference]
[\-\-owner=[\fIuser\^\fB][:.][\fIgroup\^\fB]]
[\-\-no-preserve-owner]
[\-\-version]
\fIdestination-directory\fB < \fIname-list\fR
.PP
.HS
.SH Options:
.IC \fB\-a\fR
Reset access time of input files after copying
.IC \fB\-B\fR
Change size of a block
.IC \fB\-c\fR
Write header information in ASCII rather than binary
.IC \fB\-d\fR
Create directories as needed
.IC \fB\-f\fIpattern\fR
Copy all files except those matching \fIpattern\fR
.IC \fB\-i\fR
Read the standard input
.IC \fB\-l\fR
Link files rather than copying them
.IC \fB\-m\fR
Retain previous modification times
.IC \fB\-o\fIpattern\fR
Copy all files matching \fIpattern\fR
.IC \fB\-p\fR
Read stdin for files names to copy to destination
.IC \fB\-r\fR
Interactively rename files
.IC \fB\-t\fR
Print table of contents of an existing archive
.IC \fB\-u\fR
Copy files unconditionally
.IC \fB\-v\fR
Verbose output
.HE
.B gnucpio
is the GNU version of the archive utility
.BR cpio .
It copies files into or out of a
.B cpio
or
.B tar
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.
.PP
.B gnucpio
has three operating modes.
.IP "\fICopy-out Mode\fR"
.B gnucpio
copies files into an archive.
It reads a list of file names, one per line,
from the standard input, and writes the archive onto the standard output.
.\" A typical way to generate the list of file names is with the
.\" .B find
.\" command.
.\" You should give
.\" .B find
.\" the option
.\" .B -depth
.\" to minimize problems with permissions on
.\" directories that are unwritable or not searchable.
.IP "\fICopy-in Mode\fR"
.B gnucpio
copies files from an archive or lists the archive's contents.
It reads the archive from the standard input.
Any non-option command-line arguments are shell wild-card 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 file name does
match a wildcard at the start of a pattern, and a `/' in a file name
can match wildcards.
If the command line contains no pattern,
.B gnucpio
extracts all files.
.IP "\fICopy-pass Mode\fR"
.B gnucpio
copies files from one directory tree to another.
This combines 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 copies them is given as a non-option argument.
.PP
.B gnucpio
supports the following archive formats:
binary,
old ASCII,
new ASCII,
.BR crc ,
old
.BR tar ,
and POSIX.1
.BR tar .
The binary format
is obsolete because it encodes information about the files in a way
that is not portable between different machine architectures.
The old ASCII format is portable between different machine architectures,
but should not be used on file systems with more than 65536 i-nodes.
The new ASCII format is portable between different machine architectures
and can be used on any size file system,
but is not supported by all versions of
.BR cpio ;
currently, it is only supported by GNU and \*(UN System V R4.
The
.B crc
format resembles the new ASCII format, but also contains a checksum
for each file that
.B gnucpio 
calculates when creating an archive
and verifies when the file is extracted from the archive.
.PP
.B tar
format is provided for compatability with the command
.BR tar .
It can not be used to archive a file whose name exceeds
100 characters, and cannot be used to archive block or character devices.
The POSIX.1
.B tar
format can not be used to archive a file whose name exceeds
255 characters (less unless it has a `/' in just the right place).
.PP
By default,
.B gnucpio
creates binary archives, for compatibility with older
.B cpio
programs.
When extracting from archives,
.B gnucpio
automatically recognizes the kind of archive it is reading,
and can read archives created on machines with a different byte-order.
.SH "Options"
.B gnucpio
recognizes the following command-line options.
Not every option applies to every mode.
You can prefix the long-named options with an `+' as well as with an `\-\-',
for compatibility with previous releases.
Eventually, support for `+'
will be removed, because it is incompatible with the \*(PX.
.IP "\fB\-0\fR"
.IS "\fB\-\-null\fR"
In copy-out and copy-pass modes,
read a list of file names terminated by a null character
instead of a newline.
This permits
.B gnucpio
to archive files whose names contain newlines.
.\" GNU
.\" .B find
.\" is one way to produce a list of null-terminated file names.
.IP "\fB\-a\fR"
.IS "\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.
.IP "\fB\-A\fR"
.IS "\fB\-\-append\fR"
Append to an existing archive.
Only works in copy-out mode.
The archive must be a disk file specified with the options
.B \-O
or
.BR \-F .
.IP \fB\-b\fR
.IS \fB\-\-swap\fR
In copy-in mode, swap both halfwords of words and bytes of halfwords
in the data.
Equivalent to the option
.BR  "\-sS" .
Use this option to convert 32-bit integers between big-endian and
little-endian machines.
.IP \fB\-B\fR
Set the I/O block size to 5,120 bytes.
Initially, the block size is 512 bytes.
.IP "\fB\-\-block-size=\fIblocks\^\fB"
Set the block size to \fIblocks\fR\(mu512 bytes.
.IP "\fB\-c\fR"
Use the old portable (ASCII) archive format.
.IP "\fB\-C \fIsize\fR"
.IP "\fB\-\-io-size=\fIsize\fR"
Set the I/O block size to
.I size
bytes.
.IP "\fB\-d\fR"
.IS "\fB\-\-make-directories\fR"
Create leading directories where needed.
.IP "\fB\-E file\fR"
.IS "\fB\-\-pattern-file=\fIfile\fR"
In copy-in mode,
read from
.I file
additional patterns that specify file names to extract or list.
.B gnucpio
treats the lines of
.I file
as if they had been non-option arguments to
.BR gnucpio .
.IP "\fB\-f\fR"
.IS "\fB\-\-nonmatching\fR"
Copy only the files that do
.I not
match any of the given patterns.
.IP "\fB\-F\fR"
.IS "\fB\-\-file=\fIarchive\fR"
Read to or write from
.I archive
instead of the standard input or output.
When you use this option, you do not have to specify the output device
for each volume of a multi-volume backup.
.\" To use a tape drive on another machine as the archive, use a file name that
.\" starts with `HOSTNAME:'.  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).
.IP "\fB\-\-force-local\fR"
With options
.BR \-F ,
.BR \-I ,
or
.BR \-O ,
take the archive file name to be a local file even if it contains a colon
(which ordinarily names a remote host).
.IP "\fB\-H \fIformat\fR"
.IS "\fB\-\-format=\fIformat\fR"
Use archive format
.IR format .
The valid formats are listed below;
.B gnucpio
also recognizes these names if given in capital letters.
The default in copy-in mode is to detect automatically the archive format,
and in copy-out mode is
.BR bin .
.RS
.IP \fBbin\fR
The obsolete binary format.
.IP \fBodc\fR
The old (POSIX.1) portable format.
.IP \fBnewc\fR
The new (SVR4) portable format, which supports file systems that have
more than 65536 i-nodes.
.IP \fBcrc\fR
The new (SVR4) portable format with a checksum added.
.IP \fBtar\fR
The old
.B tar
format.
.IP \fBustar\fR
The POSIX.1
.B tar
format.
Also recognizes GNU
.B tar
archives, which are similar but not identical.
.RE
.IP "\fB\-i\fR"
.IS "\fB\-\-extract\fR"
Run in copy-in mode.
.IP "\fB\-I \fIarchive\fR"
Archive file name to use instead of standard input.
.\" To use a tape drive on another machine as the archive, use a file name that
.\" starts with \fIhostname\fB:\fR.
.\" The
.\" .I hostname
.\" can be preceded by a
.\" .I 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
.\" .B .rhosts
.\" file).
.IP \fB\-k\fR
This option exists only for compatibility with other versions of
.BR cpio .
It is ignored.
.IP "\fB\-l\fR"
.IS "\fB\-\-link\fR"
Whenever possible,
link files instead of copying them.
.IP \fB\-L\fR
.IS "\fB\-\-dereference\fR"
Dereference symbolic links \(em that is,
copy the files that they point to instead of copying the links.
.IP \fB"\-m\fR"
.IS "\fB\-\-preserve-modification-time\fR"
Retain previous file-modification times when creating files.
.IP "\fB\-M \fImessage\fR"
.IS "\fB\-\-message=\fImessage\fR"
Print
.I message
when
.B gnucpio
reaches the end of a volume of the back-up medium
(such as a tape or a floppy disk),
to prompt the user to insert a new volume.
If
.I message
contains the string
.BR %d ,
.B gnucpio
replaces that string with the number of the current volume (starting at one).
.IP "\fB\-n\fR"
.IS "\fB\-\-numeric-uid-gid\fR"
In the verbose table of contents listing,
show the numeric UID and GID instead of translating them into names.
.IP "\fB\-\-no-preserve-owner\fR"
In copy-in and copy-pass modes, do not change the ownership of the
files:
leave them owned by the user who extracts them.
This is the default for non-root users, so that users on System-V \*(UN
do not inadvertantly give away files.
.IP \fB\-o\fR
.IS \fB\-\-create\fR
Run in copy-out mode.
.IP "\fB\-O \fIarchive\fR"
Write output into
.I archive
instead of to the standard output.
.\" To use a tape drive on another machine as the archive,
.\" use a file name that
.\" starts with `HOSTNAME:'.
.\" 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).
.IP "\fB\-p\fR"
.IS "\fB\-\-pass-through\fR"
Run in copy-pass mode.
.IP "\fB\-r\fR"
.IS "\fB\-\-rename\fR"
Interactively rename files.
.IP "\fB\-R [\fIuser\^\fB][:.][\fIgroup\^\fB]\fR"
.IS "\fB\-\-owner [\fIuser\^\fB][:.][\fIgroup\^\fB]\fR"
In copy-out and copy-pass modes, set the ownership of all files
created to
.I user
and
.IR group .
Either the user or the group, or both, must be present.
If the group is omitted but the `:'
or `.' separator is given,
.B gnucpio
uses the user's login group.
Only the super-user can change files' ownership.
.IP "\fB\-s\fR"
.IS "\fB\-\-swap-bytes\fR"
In copy-in mode, swap the bytes of each halfword (pair of bytes) in the files.
.IP "\fB\-S\fR"
.IS "\fB\-\-swap-halfwords\fR"
In copy-in mode, swap the halfwords of each word (four bytes) in the files.
.IP "\fB\-t\fR"
.IS "\fB\-\-list\fR"
Print a table of contents of the input.
.IP "\fB\-u\fR"
.IS "\fB\-\-unconditional\fR"
Replace all files, without asking whether to replace existing newer
files with older files.
.IP "\fB\-v\fR"
.IS "\fB\-\-verbose\fR"
List the files processed.
When used with the option
.BR \-t ,
give a listing that resembles the output of the command
.BR "ls \-l" .
In a verbose table of contents of a
.B 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 UID and GID stored in the archive.
.IP "\fB\-V \-\-dot\fR"
Print a `.' for each file processed.
.IP "\fB\-\-version\fR"
Print the number of the version of
.B gnucpio
that you are now running, and exit.
.SH Examples
The following command
copies all files and directories listed by the command
.B find
and copies them into the archive
.BR newfile.cpio :
.DM
	find . -print | cpio -oc > ../newfile.cpio
.DE
.PP
The following command reads the
.B cpio
archive
.B newfile.cpio
and extracts all files whose names
match the patterns
.B memo/al
or
.BR memo/b* :
.DM
	cpio -icdv "memo/al" "memo/b*" <../newfile.cpio
.DE
.PP
Note that the \fB\-d\fR option forces
.B cpio
to create the sub-directory
.B memo
and write the files into it.
Otherwise, the files would have been written into the current
directory.
Option
.B \-v
causes
.B cpio
to display each file name as it is extracted from the archive.
.PP
The following commands perform a multi-volume backup
of all files on mounted filesystem
.B /v
to the character-special (i.e., ``raw'') floppy device
.BR /dev/rfha0 :
.DM
	su root
	cd /v
	find . -print | cpio -ocv >/dev/rfha0
.DE
.PP
If the
.B cpio
archive exceeds one floppy disk, you will be prompted to insert another.
.SH "See Also"
.Xr "commands," commands
.Xr "cpio," cpio
.Xr "gtar" gtar
.SH Notes
\*(CO does not yet support networking.
The above descriptions of host addressing do not yet apply.
.PP
.II "Free Software Foundation"
.B gnucpio
is released under the conditions of the Free Software Foundation's
``copyleft''.
Full source code is available through the Mark Williams bulletin board.
