SYNOPSIS
cpio -i[bcdfkmrstuvBSV6] [-C size] [-E file] [-H hdr] [[-I file]
[-M msg]] [-R id] [patterns]
cpio -o[acvABLV] [-C size] [-H hdr] [[-M msg] [-O file]]
cpio -p[adlmuvLV] [-R id] directory
DESCRIPTION
Cpio creates and extracts file archives and copies files.
With the -i option, cpio works in `copy-in' mode and extracts files
from a file archive. By default, the archive is read from standard in-
put. Optional arguments are interpreted as patterns and restrict the
set of extracted files to those matching any of the patterns. A `!' at
the beginning of the pattern selects all files that do not match this
pattern. The syntax is otherwise identical to that described in
glob(7), except that the slash character `/' is matched by meta-charac-
ter constructs with `*', `?' and `['. Care must be taken to quote
meta-characters appropriately from the shell. File permissions are set
to those in the archive; if the caller is the super-user, ownerships
are restored as well. Cpio will not create directories, preserve modi-
fication times or overwrite more recently modified target files unless
the appropriate -d, -m or -u options are specified. Archives com-
pressed with bzip2(1), compress(1), gzip(1), or rpm(1) are transparent-
ly decompressed on input.
With -o, cpio works in `copy-out' mode, creates archives and writes
them to standard output per default. A list of filenames to be includ-
ed in the archive is read from standard input; if the name of a direc-
tory appears, it is included in the archive, but cpio will not include
any of its members unless they are explicitly given in addition. The
find(1) utility is useful to generate a list of files (see also its
-cpio and -ncpio operators). When producing a filename list for cpio,
find should always be invoked with -depth since this makes it possible
to extract write-protected directories for users other than the super-
user.
The -p option selects `pass' mode; a list of files is read from stan-
dard input as described for -o; files are copied to the specified di-
rectory, preserving attributes as described for -i. Special files are
re-created in the target hierarchy, and hard links between copied files
are preserved.
When a premature end-of-file is detected with -i and -o and the archive
is a block or character special file, the user is prompted for new me-
dia.
The following options alter the behavior of cpio:
-a Resets the access times of files that were included in the ar-
chive with -o or copied with -p.
-A Append files to the archive. The archive must be seekable, such
Blocks input and output archives at size byte records.
-d Creates missing parent directories for each file extracted from
the archive and allows the extraction of directories.
-E file
Each line read from file is taken as a pattern in addition to
those specified on the command line.
-f Reverses the sense of patterns such that a file that does not
match any of the patterns is selected.
-H header
Specifies the archive header format to be one of:
lfB l. crc SVR4 ASCII cpio format with checksum;
sco T{ SCO UnixWare 7.1 ASCII cpio format; T}
scocrc T{ SCO UnixWare 7.1 ASCII cpio format with
checksum; T} odc T{ traditional ASCII cpio format, as
standardized in IEEE Std. 1003.1, 1996; T} bbs byte-
swapped binary cpio format; sgi T{ SGI IRIX extended bi-
nary cpio format; T} cray T{ Cray UNICOS 9 cpio format; T}
cray5 T{ Cray UNICOS 5 cpio format; T} dec T{ Digital
UNIX extended cpio format; T} tar tar format; otar old
tar format; ustar T{ IEEE Std. 1003.1, 1996 tar for-
mat; T} l s. pax[:option,[option,...]] l l. T{
IEEE Std. 1003.1, 2001 pax format. Format-specific op-
tions are:
linkdata
For a regular file which has multiple hard links, the
file data is stored once for each link in the archive,
instead of being stored for the first entry only. This
option must be used with care since many implementations
are unable to read the resulting archive.
times
Causes the times of last access and last modification of
each archived file to be stored in an extended pax head-
er. This in particular allows the time of last access
to be restored when the archive is read.
T} sun T{ Sun Solaris 7 extended tar format; T} gnu T{
GNU tar format; T} bar T{ SunOS 4 bar format; T}
zip[:cc] T{ zip format with optional compression method.
If cc is one of en (normal, default), ex (extra), ef
(fast), or es (super fast), the standard deflate compres-
sion is used. e0 selects no compression, and bz2 selects
bzip2 compression. T}
This option is ignored with -i unless the -k option is also
present. The default for -o is binary cpio format.
-I file
-M message
The given message is printed instead of the standard one with -I
or -O when changing media.
-O file
Selects an archive file that is written instead of standard out-
put with the -o option.
-r Rename files interactively. Before a file is extracted from the
archive, its file name is printed on standard error and the user
is prompted to specify a substitute file name. If the line read
from the terminal is empty, the file is skipped; if the line
consists of a single dot, the name is retained; otherwise, the
line forms the new file name.
-R user
Set the ownership of extracted files to the user and group ids
of user instead of those specified in the archive. Valid only
for the super-user.
-s Swap bytes within each half word of input file data.
-S Swap half words within each word of input file data.
-t When combined with the -o option, a list of files in the archive
is written to standard output; no files are extracted.
-u Cpio will overwrite existing target files that were modified
more recently than the file in the archive when this option is
given.
-v Prints the file names of archived or extracted files with -i and
-o and a verbose output format with -t. If given twice (-vv) in
combination with -t when reading a zip archive, information
about compression level and method is printed.
-V Prints a dot for each archived or extracted file.
-6 Selects Unix 6th Edition archive format (only in copy-in mode).
Characteristics of archive formats are as follows:
allbox; l r r r l l1fB r2 n2 r2 c. T{ maximum user/group id
T} T{ maximum file size T} T{ maximum pathname length T} T{ bits
in dev_t (major/minor) T} binary 65535 2 GB 256 16
-H sgi 65535 9 EB 256 14/18 -H odc 262143 8
GB 256 18 -H dec 262143 8 GB 256 24/24 T{ -c,
-H crc T} 4.3e9 4 GB 1024 32/32 T{ -H sco, -H scocrc
T} 4.3e9 9 EB 1024 32/32 T{ -H cray, -H cray5 T} 1.8e19 9
EB 65535 64 -H otar 2097151 8 GB 99 n/a T{
-H tar, -H ustar T} 2097151 8 GB 256 (99) 21/21
tually need the extensions, it is identical to a binary archive.
-H sgi archives are always created in MSB order.
The odc format was introduced with System III and standardized with
IEEE Std. 1003.1. All known cpio implementations since around 1980 can
read this format.
The dec format extends the odc format to support more device bits. Ar-
chives in this format are generally incompatible with odc archives and
need special implementation support to be read.
The -c format was introduced with System V Release 4. Except for the
file size, it imposes no practical limitations on files archived. The
original SVR4 implementation stores the contents of hard linked files
only once and with the last archived link. This cpio ensures compati-
bility with SVR4. With archives created by implementations that employ
other methods for storing hard linked files, each file is extracted as
a single link, and some of these files may be empty. Implementations
that expect methods other than the original SVR4 one may extract no da-
ta for hard linked files at all.
The crc format is essentially the same as the -c format but adds a sim-
ple checksum (not a CRC, despite its name) for the data of regular
files. The checksum requires the implementation to read each file
twice, which can considerably increase running time and system over-
head. As not all implementations claiming to support this format han-
dle the checksum correctly, it is of limited use.
The sco and scocrc formats are variants of the -c and -H crc formats,
respectively, with extensions to support larger files. The extensions
result in a different archive format only if files larger than slightly
below 2 GB occur.
The cray format extends all header fields to 64 bits. It thus imposes
no practical limitations of any kind on archived files, but requires
special implementation support to be read. Although it is originally a
binary format, the byte order is always MSB as on Cray machines. The
cray5 format is an older variant that was used with UNICOS 5 and earli-
er.
The otar format was introduced with the Unix 7th Edition tar utility.
Archives in this format can be read on all Unix systems since about
1980. It can only hold regular files (and, on more recent systems,
symbolic links). For file names that contain characters with the most
significant bit set (non-ASCII characters), implementations differ in
the interpretation of the header checksum.
The ustar format was introduced with IEEE Std. 1003.1. It extends the
old tar format with support for directories, device files, and longer
file names. Pathnames of single-linked files can consist of up to 256
characters, dependent on the position of slashes. Files with multiple
links can only be archived if the first link encountered is no longer
may be extracted under wrong names and extended headers may be extract-
ed as separate files. If a file name contains non-UTF-8 characters, it
may not be archived or extracted correctly because of a problem of the
pax format specification.
The sun format extends the ustar format similar as the pax format does.
The extended headers in sun format archives are not understood by im-
plementations that support only the pax format and vice-versa. The sun
format has also problems with non-UTF-8 characters in file names.
The GNU tar format is mostly compatible with the other tar formats, un-
less an archive entry actually uses its extended features. There are
no practical limitations on files archived with this format. The im-
plementation of cpio is limited to expanded numerical fields and long
file names; in particular, there is no support for sparse files or in-
cremental backups. If cpio creates a multi-volume GNU archive, it just
splits a single-volume archive in multiple parts, as with the other
formats; GNU multi-volume archives are not supported.
The bar format is similar to the tar format, but can store longer file
names. It requires special implementation support to be read.
The zip format can be read in many non-Unix environments. There are
several restrictions on archives intended for data exchange: only regu-
lar files should be stored; file times, permissions and ownerships
might be ignored by other implementations; there should be no more than
65536 files in the archive; the total archive size should not exceed 2
GB; only deflate compression should be used. Otherwise, cpio stores
all information available with other archive formats in extended zip
file headers, so if archive portability is of no concern, the zip im-
plementation in cpio can archive complete Unix file hierarchies. Cpio
supports the zip64 format extension for large files; it automatically
writes zip64 entries if necessary. Cpio can extract all known zip for-
mat compression codes. It does not support zip encryption. Multi-vol-
ume zip archives are created as splitted single-volume archives, as
with the other formats written by cpio; generic multi-volume zip ar-
chives are not supported.
EXAMPLES
Extract all files named Makefile or makefile from the archive stored on
/dev/rmt/c0s0, overwriting recent files:
cpio -idmu -I /dev/rmt/c0s0 '[Mm]akefile' '*/[Mm]akefile'
List the files contained in a software distribution archive:
cpio -itv -I distribution.tar.gz
Write a gzip(1) compressed ustar archive containing all files below the
directory project to the file project.tar.gz, excluding all directories
named CVS or SCCS and their contents:
LANG, LC_ALL
See locale(7).
LC_CTYPE
Selects the mapping of bytes to characters used for matching
patterns.
LC_TIME
Sets the month names printed with -tv.
SYSV3 If this variable is set, the -c option has the same effect as -H
odc; -H newc can be used to select SVR4 ASCII format. The out-
put format of -tv is changed, as well as the text of diagnostic
messages.
SEE ALSO
find(1), pax(1), tar(1)
DIAGNOSTICS
Cpio exits with
l8fB l. 0 after successful operation; 1 on usage errors;
2 when operation was continued after minor errors; 3 on fatal er-
ror conditions.
NOTES
Device and inode numbers are used for hard link recognition with the
various cpio formats. Since the header space cannot hold large numbers
present in current file systems, devices and inode numbers are set on a
per-archive basis. This enables hard link recognition with all cpio
formats, but the link connection to files appended with -A is not pre-
served.
If a numeric user or group id does not fit within the size of the head-
er field in the selected format, files are stored with the user id (or
group id, respectively) set to 60001.
Use of the -A option with a zip format archive may cause data loss if
the archive was not previously created by cpio itself.
Cpio cannot store file names that contain newline characters; see the
NOTES section of find(1) for more information.
If the file names passed to cpio -o begin with a slash character, abso-
lute path names are stored in the archive and will be extracted to
these path names later regardless of the current working directory.
This is normally not advisable, and relative path names should be
passed to cpio only.
Man(1) output converted with
man2html