cpio(1) cpio(1)
NAME
cpio - copy file archives in and out
SYNOPSIS
cpio -i[bBcdfkmrsSTtuvV6] [-C bufsize] [-E file] [-G file] [-H hdr]
[-e extent_opt] [-I file [-M message]] [-R ID]] [pattern . . .]
cpio -o[aABcLvV] [-C bufsize] [-G file] [-H hdr] [-K mediasize] [-e extent_opt]
[-O file [-M message]]
cpio -p directory |[adlLmuvV] [-R ID] [-e extent_opt]
DESCRIPTION
The -i, -o, and -p options select the action to be performed.
The following list describes each of the actions (which are
mutually exclusive).
cpio -i (copy in) extracts files from the standard input (only
if -I is not specified), which is assumed to be the product of
a previous cpio -o. Only files with names that match patterns
are selected. patterns are regular expressions given in the
filename-generating notation of sh(1). In patterns, meta-
characters ?, *, and [ . . . ] match the slash (/) character,
and backslash (\) is an escape character. A ! meta-character
means not. (For example, the !abc* pattern would exclude all
files that begin with abc.) Multiple patterns may be
specified and if no patterns are specified, the default for
patterns is * (that is, select all files). Each pattern must
be enclosed in double quotes; otherwise, the name of a file in
the current directory might be used. Extracted files are
conditionally created and copied into the current directory
tree based on the options described below.
The permissions of the files will be those of the previous
cpio -o. Owner and group permissions will be the same as the
current user unless the current user possesses the owner
privilege. If this is true, owner and group permissions will
be the same as those resulting from the previous cpio -o.
NOTE: If cpio -i tries to create a file that already exists
and the existing file is the same age or younger (newer), cpio
will output a warning message and not replace the file. (The
-u option can be used to overwrite, unconditionally, the
existing file.) If file names are given as absolute pathnames
to cpio -o, then when the files are restored via cpio -i, they
will be written to their original directories regardless of
the current directory. This behavior can be circumvented by
using the -r option. When cpio is invoked from the shell,
Copyright 1994 Novell, Inc. Page 1
cpio(1) cpio(1)
each pattern should be quoted.
In normal circumstances, cpio sets the Hdr_type variable
(which defines the header type) to NONE before checking the
actual header type. It does this even if you have specified a
different header type on the command line. When you use the
-k option, however, cpio does not set Hdr_type to NONE if
you've specified a header type on the command line (with the
-c or -H option). In this case, cpio sets Hdr_type to the
header type you've specified. Thus you have a way of making
sure the correct header file type is specified, which improves
your chances of recovering files correctly. For this reason,
we recommend you specify the header type for the file (with -c
or -H) whenever you use the -k option.
cpio -o (copy out) reads the standard input to obtain a list
of pathnames and copies those files onto the standard output
(only if the -O is not specified) together with pathname and
status information.
cpio -p (pass) reads the standard input to obtain a list of
pathnames of files that are conditionally created and copied
into the destination directory tree based on the options
described below.
Access Control Lists (ACLs) are also copied with the data to
the destination file if ACLs are supported on the system and
on the destination file system.
cpio processes supplementary code set characters, and
recognizes supplementary code set characters in the message
given to the -M option (see below) according to the locale
specified in the LC_CTYPE environment variable [see LANG on
environ(5)]. In regular expressions, pattern searches are
performed on characters, not bytes, as described on sh(1).
Under the -vt option (see below), the date is displayed
according to the locale specified in the LC_TIME environment
variable.
The meanings of the available options are
-a Reset access times of input files after they have been
copied. Access times are not reset for linked files
when cpio -pla is specified.
Copyright 1994 Novell, Inc. Page 2
cpio(1) cpio(1)
-A Append files to an archive. The -A option requires the
-O option. Valid only with archives that are files, or
that are on floppy diskettes or hard disk partitions.
-b Reverse the order of the bytes within each word. (Use
only with the -i option.)
-B Input/output is to be blocked 5120 bytes to the record.
The default buffer size is device dependent when neither
this nor the -C option is used.
-c Read or write header information in ASCII character form
for portability. Always use this option (or the -H
option) when the origin and the destination machines are
different types (mutually exclusive with -H and -6).
(The -c option implies expanded fundamental types. See
NOTES for more information.)
-C bufsize
Input/output is to be blocked bufsize bytes to the
record, where bufsize is replaced by a positive integer.
The default buffer size is device dependent when neither
this nor the -B option is used. If used with -K,
bufsize must be a multiple of 1K.
-d Directories are to be created as needed.
-E file
Specify an input file (file) that contains a list of
filenames to be extracted from the archive (one filename
per line).
-e extent_opt
Specify how to handle a vxfs file that has extent
attribute information. Extent attributes include
reserved space, a fixed extent size, and extent
alignment. It may not be possible to preserve the
information if the destination file system does not
support extent attributes, has a different block size
than the source file system, or lacks free extents
appropriate to satisfy the extent attribute
requirements. Valid values for extent_opt are:
warn Issue a warning message if extent attribute
information cannot be kept (default).
Copyright 1994 Novell, Inc. Page 3
cpio(1) cpio(1)
force Fail the file save or restore or copy if
extent attribute information cannot be kept.
ignore Ignore extent attribute information entirely.
-f Copy in all files except those in patterns (See the
paragraph about cpio -i for a description of patterns.)
-G file
NOTE: This option is intended for use by front-end or
application programs that invoke cpio. If you're
running cpio at the shell level, you probably won't need
this option.
The -G option allows a program to specify file as the
interface through which cpio communicates with a user.
Specifically, this interface is used for end-of-medium
processing (but it also affects where -r gets done); it
is used both for writing the prompts to the user and for
reading the user's input. By default, /dev/tty is the
interface. However, in some situations (such as
graphics application environments), /dev/tty is not
available. Therefore an alternative interface, such as
a pseudo-tty, may be needed.
If the argument to -G is the keyword STDIO, it will
print prompts (to change the media, and also for new
file names when the -r option is used) on stdout, and
read responses from stdin.
-H hdr
Read or write header information in hdr format. Always
use this option or the -c option when the origin and the
destination machines are different types (mutually
exclusive with -c and -6). Valid values for hdr are:
crc or CRC ASCII header with expanded fundamental
types and an additional per-file
checksum (see NOTES)
ustar or USTAR IEEE/P1003 Data Interchange Standard
header and format
tar or TAR tar header and format
Copyright 1994 Novell, Inc. Page 4
cpio(1) cpio(1)
odc ASCII header with small fundamental
types (see NOTES)
-I file
Read the contents of file as an input archive. If file
is a character special device, and the current medium
has been completely read, replace the medium and press
RETURN to continue to the next medium. This option is
used only with the -i option.
-k Attempt to skip corrupted file headers and I/O errors
that may be encountered. If you want to copy files from
a medium that is corrupted or out of sequence, this
option lets you read only those files with good headers.
(For cpio archives that contain other cpio archives, if
an error is encountered, cpio may terminate prematurely.
cpio will find the next good header, which may be one
for a smaller archive, and terminate when the smaller
archive's trailer is encountered.) Used only with the
-i option.
-K mediasize
Specify the media size as a multiple of 1K. If used
with -C bufsize, then bufsize must be a multiple of 1K.
Use only with the -o option.
-l Whenever possible (only with the -p option), link files
rather than copying them. (Even if a file cannot be
linked, it will be copied.)
-L Follow symbolic links. The default is not to follow
symbolic links.
-m Retain previous file modification time. The
modification time and access time of a restored file is
set to the modification time of the file when it was
backed up. Modification time of directories is not
retained.
-M message
Define a message to use when switching media. When you
use the -O or -I options and specify a character special
device, you can use this option to define the message
that is printed when you reach the end of the medium.
One %d can be placed in message to print the sequence
number of the next medium needed to continue. message
Copyright 1994 Novell, Inc. Page 5
cpio(1) cpio(1)
may contain supplementary code set characters.
-O file
Direct the output of cpio to file. If file is a
character special device and the current medium is full,
replace the medium and type a carriage return to
continue to the next medium. Use only with the -o
option. Using this option with -o guarantees exclusive
access to the character special device or output file.
Redirecting output to a device or file does not
guarantee exclusive access and could result in a
corrupted archive if a second process opens the device
or file while the first process is still active.
-r Interactively rename files. If the user types a
carriage return alone, the file is skipped. If the user
types a ``.'' the original pathname will be retained.
(Should be used only with cpio -i.)
-R ID Reassign ownership and group information for each file
to user ID (ID must be a valid login ID from
/etc/passwd). This option is valid only for a
privileged user.
-s Swap bytes within each half word.
-S Swap halfwords within each word.
-t Print a table of contents of the input. No files are
created (mutually exclusive with -V).
-T Truncate long file names to 14 characters. Use only
with the -i option.
-u Copy unconditionally (normally, an older file will not
replace a newer file with the same name).
-v Verbose: causes a list of file names to be printed.
When used with the -t option, the table of contents
looks like the output of an ls -l command [see ls(1)];
dates are displayed according to the locale specified in
the LC_TIME environment variable [see LANG on
environ(5)].
Copyright 1994 Novell, Inc. Page 6
cpio(1) cpio(1)
-V Special Verbose: print a dot for each file read or
written. Useful to assure the user that cpio is working
without printing out all file names.
-6 Process a UNIX System Sixth Edition archive format file.
Use only with the -i option (mutually exclusive with -c
and -H).
NOTE: cpio assumes four-byte words.
If, when writing to a character device (-o) or reading from a
character device (-i), cpio reaches the end of a medium (such
as the end of a diskette), and the -O and -I options aren't
used, cpio will print the following message:
End of medium on input (output). To continue, type device/file name when ready.
To continue, you must replace the medium and type the
character special device name (/dev/rdsk/f0 for example) and
press RETURN. You may want to continue by directing cpio to
use a different device. For example, if you have two floppy
drives you may want to switch between them so cpio can proceed
while you are changing the floppies.
USAGE
Output (-o)
When standard input is directed through a pipe to cpio -o,
files are grouped so they can be redirected (>) to a single
file (../newfile). The -c option insures that the file will
be portable to other machines (as would the -H option).
Instead of ls(1), you could use find(1), echo(1), cat(1), and
so on, to pipe a list of names to cpio. You could redirect
the output to a device instead of a file.
ls | cpio -oc > ../newfile
Input (-i)
cpio -i uses the output file of cpio -o (directed through a
pipe with cat in the example below), extracts those files that
match the patterns (memo/a1, memo/b*), creates directories
below the current directory as needed (-d option), and places
the files in the appropriate directories. The -c option (with
-k) is used if the input file was created with a portable
header. If no patterns were given, all files from newfile
would be placed in the directory.
Copyright 1994 Novell, Inc. Page 7
cpio(1) cpio(1)
cat newfile | cpio -ickd "memo/a1" "memo/b*"
Pass (-p)
cpio -p takes the file names piped to it and copies or links
(-l option) those files to another directory (newdir in the
example below). The -d option allows you to create
directories as needed. The -m option lets you retain the
modification time and security level. [It is important to use
the -depth option of find(1) to generate pathnames for cpio.
Use of this option eliminates problems cpio could have in
trying to create files under read-only directories.] The
destination directory, newdir, must exist.
find . -depth -print | cpio -pdlmv newdir
Note that when you use cpio in conjunction with find, if you
use the -L option with cpio then you must use the -follow
option with find and vice versa. Otherwise there will be
undesirable results.
EXIT CODES
1 usage error
2 file error (but cpio completes, displaying error
number)
3 fatal error (cpio dies immediately)
Reading from magnetic tape in any fixed-length block length
besides the block length that the media was written in
originally will cause an I/O error. If you want to read a
tape that was written using a block-length besides the default
of 512, you must use the tapecntl(1) command ( qv ) to either
set the block-length of the drive to match the block length of
the media or to set the drive into variable block length mode.
Files
/usr/lib/locale/locale/LC_MESSAGES/uxcore.abi
language-specific message file [See LANG on environ(5).]
REFERENCES
ar(1), archives(4), cat(1), echo(1), find(1), ls(1), tar(1)
NOTICES
An archive created with the -c option on a System V Release 4
system cannot be read on System V Release 3.2 systems, or
Copyright 1994 Novell, Inc. Page 8
cpio(1) cpio(1)
earlier. Use the -H odc option, which is equivalent to the
header created by the -c option in earlier System V Releases,
if the cpio image will be read by a pre-System V Release 4
version of cpio.
In releases of UNIX System V prior to Release 4, symbolic
links are not understood. The result of copying in a symbolic
link on an older release will be a regular file that contains
the pathname of the referenced file.
Pathnames are restricted to 256 characters for the binary (the
default) and -H odc header formats. Otherwise, pathnames are
restricted to 1024 characters.
The default binary header format and the ODC header format do
not support expanded fundamental types (EFTs). Smaller,
preSVR4-type sizes are assumed by these header formats. If
you are trying to use cpio over file systems with EFT and one
of these two header formats are used, you will get the error
message Old format cannot support expanded types. Use the -c
or the -Hcrc options instead. See archives(4) for details on
type sizes.
Only a privileged user can copy block or character special
files.
Blocks are reported in 512-byte quantities.
The st01 tape driver does not always require block sizes that
are in multiples of 512 bytes, but block size is device
dependent. Use tapecntl to set the tape driver to use the
block size supported by the tape device. Failure to set the
block size correctly will result in an error when the driver
attempts to write a block of the unsupported size.
If a file has 000 permissions and contains more than 0
characters of data, and the user does not have the appropriate
privilege, the file will not be saved or restored.
When attempting to redirect standard input or standard output
from or to a block or character special device you may get an
error message such as Cannot read from device or Cannot write
to device. The appearance of such a message does not
necessarily mean a true I/O error has occurred. It is more
likely to mean the user does not have access to that device;
the user should ask the system administrator to allocate the
Copyright 1994 Novell, Inc. Page 9
cpio(1) cpio(1)
device for him or her.
Prior to Release 4, the default buffer size was 512 bytes.
Beginning with Release 4, the default buffer size is optimized
for the device and using the -C option to specify a different
block size may cause cpio to fail. Therefore, care must be
taken when choosing the block size. To avoid wasting space on
streaming tape drives, use the -C option and specify an
appropriate block size.
Using variable-length block mode when writing magnetic tapes
is discouraged because it may not work correctly in releases
before SVR4.2 MP. Magnetic tape should always be written in
fixed-length block mode, even though you are free to change
the default fixed-block length from 512 bytes to any other
fixed-block mode the tape drive supports.
Reading from magnetic tape in any fixed-length block length,
besides the block length that the media was written in
originally, will cause an I/O error. In order to read a tape
that was written using some block length besides the default
of 512, use the tapecntl(1) command (qv) to either set the
block length of the drive to match the block length of the
media, or to set the drive into variable block length mode.
It is not desirable for device overwriting to be the ordinary
behavior for cpio even when the -u option is specified. This
has been done for system resiliance. If a device on an archive
being read in does not match a device that is already on the
system, it is almost always the case that the device on the
archive is different because the archive was exported from
another system that had different device numbers. To overwrite
existing devices in such a situation could be crippling to the
system, depending on which devices are overwritten and what
the change is.
Copyright 1994 Novell, Inc. Page 10