cpio - copy file archives in and out
cpio -i[bBcdfkmrsStuvTV6] [-C bufsize] [-E file] [-H hdr] [-I file [-M
message]] [-R ID]] [pattern . . .]
cpio -o[aABcKLvVW] [-C bufsize] [-H hdr] [-O file [-M message]]
cpio -p[adlLmuvVW] [-R ID] directory
The -i, -o, and -p options select the action to be performed. The
following list describes each of the actions (which are mutually
cpio -i (copy in) extracts files from the standard input, 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, metacharacters
?, *, 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 the same as those at the time of the
previous cpio -o, subject to modification by the current umask value.
Use a umask of 0 if you want the modes to match the original modes. The
owner and group of these files will be those of the current user, unless
the current user is super-user. If this is true, the permissions, owner,
and group of the files will be the same as those at the time of 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
cpio -o (copy out) reads the standard input to obtain a list of pathnames
and copies those files onto the standard output 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.
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 (mutually exclusive with -m). See NOTES (see below) for
additional error information.
-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
-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. (-B does not apply to the pass option.)
-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 device
numbers, thus is not POSIX compliant)
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.
(-C does not apply to the pass option.)
-d Directories are to be created as needed.
Specify an input file (file) that contains a list of filenames to be
extracted from the archive (one filename per line).
-f Copy in all files except those in patterns. (See the paragraph on
cpio -i for a description of patterns.)
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 device numbers and an
additional per-file checksum (Not POSIX compliant,
since header format is different)
ustar or USTAR IEEE/P1003 Data Interchange Standard header and
tar or TAR tar header and format
odc ASCII header with small device numbers
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
The specified file can also reference a remote tape device. A remote
tape device name has the form:
Where system is the remote system, /dev/??? is the particular drive
on the remote system (raw, rewinding, non-rewinding, etc.), and the
optional user is the login name to be used on the remote system, if
different from the current user's login name.
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 Required for files larger than 2 Gigabytes. Cpio will issue a
warning and skip such files if an attempt is made to archive them
without specifying the -K flag. Used only with the -o option.
Mutually exclusive with -c, -H options. Because the -c option can
not be used, device files with major numbers greater than 127 or
minor numbers greater than 255 could not normally be archived; the
binary format is extended with this option so that those device
files can be backed up, but will not be able to be restored on older
or non-IRIX versions of cpio with the correct major and minor
number. Warning: Use of this option may result in the creation of
an archive that is not portable to other machines; a warning is
issued on the first file causing the archive to not be portable.
-l Whenever possible, link files rather than copying them. (Usable
only with the -p option.) If the link fails a error message will be
displayed and then cpio will attempt to copy the file.
-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. This option is ineffective on
directories that are being copied. This option is mutually
exclusive with -a.
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 may
contain supplementary code set characters.
Direct the output of cpio to file. If file is a character special
device and the current medium is full, replace the medium and press
the RETURN key to continue to the next medium. Use only with the -o
-r Interactively rename files. If the user presses the RETURN key
alone, the file is skipped. If the user types a ``.'' the original
pathname will be retained. (Not available with cpio -p.)
Reassign ownership and group information for each file to user ID
(ID must be a valid user ID from /etc/passwd). This option is valid
only for a super-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 Test (verify) the contents of the archive against the files in the
filesystem. A = is printed in the first column if the file is the
same, otherwise !. If given as -TT, a second = or ! is output,
based on the owner, group, and permissions matching, and in the case
of symbolic links, the contents of the symbolic link.
-W Detect and handle specially files with holes (sections of a file
with no disk blocks allocated to it, normally caused by seeking over
a section of the file while it is being created). Holey files are
marked specially in the archive, and a block map is written at the
start of a file. Only the non-hole sections are written to the
archive, normally requiring much less space than when this option is
When used, and holey files are found, the archive will not be
compatible with other versions of cpio (non-IRIX versions, or IRIX
versions older than IRIX 6.5); a warning is issued on the first file
causing the archive to not be portable. Used only with the -o
option. Mutually exclusive with -c, -H options. When the -v option
is used, the type is printed as H for holey files, rather than -.
-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
-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
-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
(-i), cpio reaches the end of a medium (such as the end of a tape), and
-O and -I options aren't used, cpio will print the following message:
If you want to go on, type device/file name when ready.
To continue, you must replace the medium and type the character special
device name (/dev/tape for example) and press RETURN. You may want to
continue by directing cpio to use a different device. For example, if
you have two tape drives you may want to switch between them so cpio can
proceed while you are changing the tapes. (Simply pressing RETURN causes
the cpio process to exit.)
The following examples show three uses of cpio.
When standard input is directed through a pipe to cpio -o, files are
grouped so they can be directed (>) 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 direct the
output to a device instead of a file.
ls | cpio -oc > ../newfile
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 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.
cat newfile | cpio -icd "memo/a1" "memo/b*"
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 says to create directories as needed. The -m option says retain
the modification time. (It is important to use the -depth option of
find(1) to generate pathnames for cpio. This eliminates problems cpio
could have 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.
language-specific message file [See LANG on environ (5).]
ar(1), cat(1), echo(1), find(1), ls(1), tar(1), umask(1), attr(1),
An archive created with the -c option (defaults to an ASCII header with
expanded device numbers and an additional per-file checksum - CRC) on a
Release 4 system cannot be read on System V Release 3.2 systems, or
As noted in the option descriptions above, use of the -W or -K options
may cause the resulting archive to be non-portable, and possibly not even
usable, on older versions (prior to IRIX 6.5), or other operating
systems. The types of files that might cause problems are those larger
than 2 Gbytes, files with holes (no data blocks), and device files with
major numbers larger than 127 or minor numbers larger than 255.
Use the -H odc option in the current version of cpio (ie. IRIX 5.X
Operating system), which is equivalent to the header created by the -c
option in earlier System V releases (ie. IRIX 4.0.X Operating System).
This is to be used when reading previously created cpio image(s) on a
System V Release 4 systems (ie. IRIX 5.X Operating system).
cpio will issue a warning and continue archiving when the block or
character device numbers are truncated when using the -H odc option.
cpio will issue a warning and continue archiving when the userid or group
id of associated with a file is too large. The userid for the user
``nobody'' will be substituted. The limits are 65535 for binary
(default) format, and 262143 for -H ustar, -H tar and -H odc formats.
There is no limit for -H crc or -c formats.
It is common to construct a list of file names with find or other
commands to pipe to cpio. Filenames with embedded white space will work
this way, with the exception of filenames with embedded newlines, since
each filename in the list is terminated by a newline. This may sometimes
produce confusing error messages.
If the Byte swapped data - re-try with correct device message occurs,
check to make sure that the correct device (switched or non-switched) is
begin used to dump the media (see tps(7M)).
Path names are restricted to 256 characters for the binary (the default)
and -H odc header formats. Otherwise, pathnames are restricted to 1024
Only a super-user user can copy special files. Additionally, when
running from a setuid program (or if made setuid itself), some files may
still not be accessible, since the effective userid is checked in several
places, rather than the real userid. This is deliberate.
Blocks are reported in 512-byte quantities.
If a file has 000 permissions, contains more than 0 characters of data,
and the user does not have the appropriate access to the file, the file
will not be saved or restored.
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, the -C option with an appropriate
block size should be used.
When using the -a option (resets the access times of the input files)
cpio cannot reset the access time of the files in /dev/fd. This is
because these are special "file descriptor files" (see fd(4)). These
"file descriptor files" cannot have there access times reset with cpio or
utime(2). cpio with the -a option will issue the warning message(s)
"Cannot reset time on "/dev/fd/XX" : Operation not supported" when
confronted with these files.
Extended Attributes such as file ACL's, capability sets, and MAC labels
are not archived or restored using bru. See attr(1) for more information
about Extended Attributes and see xfsdump(1m) or tar(1M) with the -M
option, for a method to back them up.
PPPPaaaaggggeeee 8888 [ Back ]