cpio(1) cpio(1)
NAME
cpio - copy files and directories in and out
SYNOPSIS
cpio -o[addoption ...] [singleoption ...] Format 1
cpio -i[addoption ...] [singleoption ...] [pattern ...] Format 2
cpio -p[addoption ...] [singleoption] directory Format 3
DESCRIPTION
The cpio command has three functions:
- it copies one or more files into an archive file (Format 1)
- it retrieves files from an archive previously created with cpio,
tar or pax (Format 2)
- it copies files into a directory (Format 3)
Only the main options -o, -i, -p, and -e are detailed in the descrip-
tions of the above three formats. The remaining options are explained
in the section on ADDITIONAL and SINGLE OPTIONS. The various options
permitted with each format are indicated in the format descriptions.
OPTIONS
Format 1: Copy files out
cpio -o[addoption ...] [singleoption ...]
addoption
a, A, B, c, L, q, v, V
singleoption
-C bufsize, -H header, -O archive [-M message], -R userid
Main options
-o (out) cpio reads a list of path names of plain files from stan-
dard input and copies these files along with some status informa-
tion to standard output in a special archive format. Output is
padded to a 512-byte boundary. The number of 512-byte blocks
copied is written to standard error.
Page 1 Reliant UNIX 5.44 Printed 11/98
cpio(1) cpio(1)
When the Veritas File System (VxFS) is installed on the system, the
following additional option is available:
-e extentop
Specify how to process extent attribute information. This option
specifies the required persistence of extent attributes when pro-
cessing files which have preallocated space or fixed extent
sizes. Valid values for extentop are:
warn issue a warning message if extent attribute information
cannot be kept (the default behavior if this option is
not specified).
force fail the file save if extent attribute information can-
not be kept.
ignore ignore extent attribute information.
Format 2: Copy files in
cpio -i[addoption ...] [singleoption ...] [pattern ...]
addoption
b, B, c, d, f, k, m, r, s, S, t, u, v, V, 6
singleoption
-C bufsize, -E file, -H header, -I archive [-M message], --
Main options
-i (in) cpio reads from an archive created beforehand with
cpio/tar/pax. The archive must be sent to cpio via standard
input. cpio fetches from input those files whose names match with
pattern. These files are created and copied into the current
directory tree in accordance with the additional options that you
specify. The extracted files have the same permissions as the
files copied out with cpio/tar/pax, while the user ID and group
ID are those of the user calling cpio -i. It is only when the
system administrator calls cpio -i that the extracted files
retain the same user or group ID as the files copied out with
cpio/tar/pax. Only the system administrator can extract special
files.
The number of 512-byte blocks read is output by cpio to standard
error.
Page 2 Reliant UNIX 5.44 Printed 11/98
cpio(1) cpio(1)
When the Veritas File System (VxFS) is installed on the system, the
following additional option is available:
-e extentop
Specify how to process extent attribute information. This option
specifies the required persistence of extent attributes when pro-
cessing files which have preallocated space or fixed extent
sizes. Valid values for extentop are:
warn issue a warning message if extent attribute information
cannot be kept (the default behavior if this option is
not specified).
force fail the file restore if extent attribute information
cannot be kept.
ignore ignore extent attribute information.
pattern
pattern specifies the files to be selected from the input. All
shell metacharacters for file name generation can be used in
defining pattern. The maximum length for a pattern is 1024 char-
acters.
pattern not specified:
Has the same effect as entering an asterisk *, i.e. all files are
extracted, even those with names that begin with a dot.
Format 3: Copy files to a directory
cpio -p[addoption ...] [singleoption] directory
addoption
a, d, l, L, m, u, v, V
singleoption
-R userid, --
Main options
-p (pass) cpio reads a list of path names of plain files, creates
the corresponding files, and copies them to the named directory,
in accordance with the additional options that you specify. The
number of 512-byte blocks copied by cpio is written to standard
error.
Page 3 Reliant UNIX 5.44 Printed 11/98
cpio(1) cpio(1)
When the Veritas File System (VxFS) is installed on the system, the
following additional option is available:
-e extentop
Specify how to process extent attribute information. This option
specifies the required persistence of extent attributes when pro-
cessing files which have preallocated space or fixed extent
sizes. Valid values for extentop are:
warn issue a warning message if extent attribute information
cannot be kept (the default behavior if this option is
not specified).
force fail the file save or restore if extent attribute infor-
mation cannot be kept.
ignore ignore extent attribute information.
directory
Name of the destination directory to which the files are to be
copied. The path name must not be more 1024 characters long.
ADDITIONAL and SINGLE OPTIONS (for all 3 formats)
The additional options must follow the main options immediately and be
specified without a minus sign or blanks, e.g. cpio -pdl.
Single options are specified after the additional options; they must
be preceded by a minus sign and followed by associated arguments, e.g.
cpio -oBcv -O /dev/ios0/stape004.
a (access time) Resets access times of input files after they have
been copied.
Access times are not reset for linked files when option l is also
specified.
Options a and m are mutually exclusive and must not be combined.
A Appends files to an existing archive. The -A option can only be
combined with single option -O archive. It is only valid for
archives which are files or which are on floppy disk(s) or hard
disk partitions. Open-reel tapes and tape cartridges are not sup-
ported.
b (bytes) Reverses the byte sequence within each word. A word is
equivalent to 4 bytes.
This option can only be combined with main option -i.
Page 4 Reliant UNIX 5.44 Printed 11/98
cpio(1) cpio(1)
B (block) Input/output is to be blocked 5120 bytes to the record.
The default buffer size is 512 bytes when this option and single
option -C are not used. When listing the blocks which it is read-
ing in or out, cpio generally assumes a block size of 512 bytes.
Option -B is only meaningful with data directed to or from a
character special file.
Archives written with a particular block size may not be read
with a smaller block size. In contrast, smaller block sizes are
detected automatically when they are read from the archive.
This option must not be combined with main option -p.
c (compatible) cpio writes or reads header information in US ASCII
format for compatibility reasons.
You should always use this additional option (or single option
-H) when the source and target machines are of different types.
Options c, 6, and -H are mutually exclusive and must not be com-
bined.
Note: Archives created with c in Version 5.40 cannot be read on
systems that have an earlier UNIX version installed. Use
single option -H odc if you want your archive to be read-
able on a system with an earlier operating system version.
A header created with -H odc corresponds to a header
created with c on an earlier version.
To ensure compatibility with System V Release 3.2 and ear-
lier releases, cpio does not usually back up files with
inode numbers above 65535. To ensure that such files are
backed up, you should use additional option c.
Attention: You must use this format for files larger than
2 GB. A warning is issued in this case.
-C bufsize
Input/output is to be blocked bufsize bytes to the record, where
bufsize must be a positive integer. For floppy disks, bufsize
must be a multiple of 512 bytes (one floppy sector). The default
buffer size is 512 bytes when this option and additional option B
are not used.
This option must not be combined with main option -p.
d (directory) Directories are automatically created as needed.
Page 5 Reliant UNIX 5.44 Printed 11/98
cpio(1) cpio(1)
-E file
(extract) Specify an input file file that contains a list of file
names to be extracted from the archive. Only one file name per
line may be given; however, you can additionally specify a pat-
tern as well.
f Only the files not matching pattern are copied.
-H header
cpio reads or writes header information in header format. You
should always use this option or the c option when the source and
target machines are of different types.
The following header formats are permitted:
crc ASCII header with expanded inode numbers and an addi-
tional per-file checksum
ustar IEEE/P1003 Data Interchange Standard header and format
tar tar-style header and format
odc ASCII header with small inode numbers
When exchanging data with a computer that has a SINIX version
earlier than SINIX V5.40 installed, you should use single option
-H odc. Headers created with -H odc in SINIX V5.40 are equivalent
to headers created with c on earlier SINIX versions.
Path names are restricted to 256 characters for the binary (the
default) and -H odc header formats. Otherwise, a maximum of 1024
characters are permitted.
Inode numbers of files backed up with -H odc must not be above
262143 (777777 octal).
-I archive
(input) This option can only be combined with main option -i.
cpio reads input from the named archive.
k This option can only be combined with main option -i.
cpio attempts to skip any corrupted file headers and I/O errors
that it encounters. If you want to copy files from a medium that
is partially corrupted, this option lets you read only those
files with good headers. In the case of archives that contain
other cpio archives, cpio may terminate prematurely if an error
occurs. cpio will then find the next good header, which may be
one for a smaller archive, and terminate when it encounters the
smaller archive's trailer.
Page 6 Reliant UNIX 5.44 Printed 11/98
cpio(1) cpio(1)
l (link) This option can only be combined with option -p.
To save storage space when working with a large number of files,
whenever possible, the files should be linked rather than copied
to another directory.
L (symbolic links) If this option is set, cpio follows symbolic
links. The result of copying in a symbolic link on an earlier
version will be a regular file that contains the path name of the
file referenced by the symbolic link. Note that if you use the L
option with cpio in conjunction with find(1), then you must use
find's follow option.
m (modification time) Retains the previous file modification time.
This option is not effective on directories. Options m and a are
mutually exclusive and must not be combined.
-M message
(message) Defines a message to be used when switching media. When
you use the -O or -I options and specify a character special
file, you can use this option to define the message that is
printed when you reach the end of the volume. One %d can be
placed in message to print the sequence number of the next volume
needed to continue. You may specify more than one word for
message, provided you enclose the string in double quotes
("...").
-O archive
(output) This option can only be combined with main option -o.
cpio directs its output to the named archive.
-q (quick) cpio in fast mode. The ipc facilities are allocated now.
A child is forked to do the reading and the parent will do the
writing to the device.
The -q option can only be combined with main option -o.
r (rename) Allows files to be renamed interactively during copying.
cpio prompts for a new name for each file. If you answer by sim-
ply pressing <RETURN>, the file will not be renamed.
The r option does not work with open-reel tapes, tape cartridges
or Video 8 cartridges.
-R userid
(reassign) This option is only available to the system adminis-
trator. cpio reassigns ownership and group information for each
file in accordance with the specified userid, which must be a
valid user ID from /etc/passwd file.
Page 7 Reliant UNIX 5.44 Printed 11/98
cpio(1) cpio(1)
s (swap) This option can only be combined with main option -i. It
causes bytes to be swapped within each half word. A word is
equivalent to 4 bytes.
S (swap) This option can only be combined with main option -i. It
causes halfwords to be swapped within each word. A word is
equivalent to 4 bytes.
t (table of contents) Produces a table of contents of the source
from which the files are to be read. No files are copied.
u (unconditional) Replaces an existing file with an extracted file
with the same path name even if the existing file has a more
recent access date than the one being extracted.
u not specified:
Existing files are replaced by extracted files (with the same
path name) only if the existing files are older than the
extracted ones.
v (verbose) Causes the names of files to be output as they are
being copied in or out. If v is used in conjunction with t,
detailed information about the files will be provided as well.
V (special verbose) Prints a dot for each file read or written.
This option is useful to assure the user that cpio is working
without providing detailed information.
6 This option may only be used in combination with option -i.
cpio processes a UNIX System Sixth Edition archive format file.
Options c, -H and 6 are mutually exclusive.
-- If the first argument begins with a dash (-), the end of the
command-line options must be marked with --.
MESSAGES
Warning: just archiving file filename > 2GB.
cpio format unable to handle filename - filesize > 2GB.
Please use -c Option.
Error: Old format cannot support expanded types on filename
You did not use the c option. To ensure compatibility, the way in
which cpio handles the inode of its files means that inodes
beyond 64 Kb cannot be processed unless you use the c option.
Page 8 Reliant UNIX 5.44 Printed 11/98
cpio(1) cpio(1)
LOCALE
The LCMESSAGES environment variable governs the language in which
message texts are displayed. With regular expressions in square brack-
ets the LCCOLLATE environment variable governs the scope of ranges,
equivalence classes and collating elements, while the LCCTYPE envi-
ronment variable governs the scope of character classes.
The LCTIME environment variable governs the format of date and time
strings in archive table-of-contents listings produced by the -v
option.
If LCMESSAGES, LCCOLLATE, LCCTYPE or LCTIME is undefined or is
defined as the null string, it defaults to the value of LANG. If LANG
is likewise undefined or null, the system acts as if it were not
internationalized.
If any of the locale variables has an invalid value, the system acts
as if none of the variables were set.
The LCALL environment variable governs the entire locale. LCALL
takes precedence over all the other environment variables which affect
internationalization.
EXAMPLES
Example 1
All files in the current directory with names that end in .f are to be
copied out to an archive file named f.progs:
$ find . -name '*.f' -print | cpio -o >f.progs
56 blocks
find . -name '*.f' searches the current directory for file names that
end in .f and writes them to the standard output, which is piped (|)
to the standard input of cpio. cpio -o then reads the file names and
copies the appropriate files along with status information to standard
output. The "greater than" symbol > redirects the standard output to
the file f.progs. When it has finished, cpio writes the number of
copied blocks on standard error.
Example 2
The contents of a directory and all its subdirectories are to be
copied to a tape cartridge:
$ find . -print | cpio -oBv -H odc -O /dev/ios0/stape004
find searches the current directory and any subdirectories and writes
the relative path names of all the files that it finds to standard
output. The standard output of find is piped (|) to the standard input
of cpio. cpio reads the file names and copies the files to the tape
cartridge, retaining the structure of the directory tree. The names of
Page 9 Reliant UNIX 5.44 Printed 11/98
cpio(1) cpio(1)
the files being copied are echoed on the standard output (option v).
Option B is used to increase the buffer size, option -H odc to ensure
that the tape is readable on machines of different types. You should
use the -H odc option whenever possible to ensure compatibility with
other systems.
Example 3
All files whose names end with .c (= pattern) must be extracted from
the file.cpio archive:
$ cpio -ivmdB *.c <file.cpio
Example 4
An archive on a magnetic tape cassette on device /dev/ios0/rstape003
is to be extracted:
$ cpio -ivdB /dev/ios0/rstape003
Example 5
The directory named dir.old is to be copied together with all its sub-
directories. The duplicate directory is to be named dir.new:
$ cd dir.old
$ find . -depth -print | cpio -pdl dir.new
The cd command switches you to the directory dir.old. find then
searches this directory and any subdirectories and writes the names of
all the files that it finds to standard output. The standard output of
find is piped (|) to the standard input of cpio. cpio reads the file
names and copies the files to the directory dir.new (-p dir.new).
Directories are created as needed (-d), i.e. all subdirectories of
dir.old are copied recursively. Since option -l is also specified, the
files, where possible, are not actually copied but linked.
SEE ALSO
ar(1), cat(1), echo(1), find(1), ls(1), mt(1), pax(1), tar(1), ar(4),
archives(4).
Page 10 Reliant UNIX 5.44 Printed 11/98