Synopsis

Description

The cpio command copies files into and out of a cpio archive.
The cpio archive can span multiple volumes. The -i, -o, and -p
options select the action to be performed. The following list describes each of
the actions. These actions are mutually exclusive.

Copy In Mode

cpio-i (copy in) extracts files from the standard input, which is
assumed to be the product of a previous cpio-o command. Only
files with names that match one of the patterns are selected. See sh(1)
and OPERANDS for more information about pattern. Extracted files are conditionally copied
into the current directory tree, based on the options described below. The permissions
of the files are those of the previous cpio -o command. The owner
and group are the same as the current user, unless the current
user has the {PRIV_FILE_CHOWN_SELF} privilege. See chown(2). If this is the case,
owner and group are the same as those resulting from the previous
cpio -o command. Notice that if cpio-i tries to create a file that
already exists and the existing file is the same age or younger
(newer), cpio outputs a warning message and not replace the file. The
-u option can be used to unconditionally overwrite the existing file.

Copy Out Mode

cpio-o (copy out) reads a list of file path names from
the standard input and copies those files to the standard output, together
with path name and status information in the form of a cpio
archive. Output is padded to an 8192-byte boundary by default or to the
user-specified block size (with the -B or -C options) or to some
device-dependent block size where necessary (as with the CTC tape).

Pass Mode

cpio-p (pass) reads a list of file path names from the
standard input and conditionally copies those files into the destination directory tree,
based on the options described below.

If the underlying file system of the source file supports detection of
holes as reported by pathconf(2), the file is a sparse file, and
the destination file is seekable, then holes in sparse files are preserved in
pass mode, otherwise holes are filled with zeros.

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, and the
-O and -I options are not used, cpio prints the following message:

To continue, type device/file name when ready.

To continue, you must replace the medium and type the character special
device name and press RETURN.

Options

The following options are supported:

-i

(copy in) Reads an archive from the standard input and conditionally extracts the files contained in it and places them into the current directory tree.

-o

(copy out) Reads a list of file path names from the standard input and copies those files to the standard output in the form of a cpio archive.

-p

(pass) Reads a list of file path names from the standard input and conditionally copies those files into the destination directory tree.

The following options can be appended in any sequence to the -i,
-o, or -p options:

-0

Reads a list of filenames terminated by a null character, instead of a NEWLINE, so that files whose names contain NEWLINESs can be archived. Using find with the-print0 option is one way to produce such a list of filenames.

This option may be used in copy-out and copy-pass modes.

-a

Resets access times of input files after they have been copied, making cpio's access invisible. Access times are not reset for linked files when cpio-pla is specified.

-A

Appends files to an archive. The -A option requires the -O option. Valid only with archives that are files or that are on hard disk partitions. The effect on files that are linked in the existing portion of the archive is unpredictable.

-b

Reverses the order of the bytes within each word. Use only with the -i option.

-B

Blocks input/output 5120 bytes to the record. The default buffer size is 8192 bytes when this and the -C options are not used. -B does not apply to the -p (pass) option.

-c

Reads or writes header information in ASCII character form for portability. There are no UID or GID restrictions associated with this header format. Use this option between SVR4-based machines, or the -Hodc option between unknown machines. The -c option implies the use of expanded device numbers, which are only supported on SVR4-based systems. When transferring files between SunOS 4 or Interactive UNIX and the Solaris 2.6 Operating environment or compatible versions, use -Hodc.

-Cbufsize

Blocks input/output bufsize bytes to the record, where bufsize is replaced by a positive integer. The default buffer size is 8192 bytes when this and -B options are not used. -C does not apply to the -p (pass) option.

-d

Creates directories as needed.

-Efile

Specifies an input file (file) that contains a list of filenames to be extracted from the archive (one filename per line).

-f

Copies in all files except those in patterns. See OPERANDS for a description of pattern.

-Hheader

Reads or writes header information in header format. Always use this option or the -c option when the origin and the destination machines are different types. This option is mutually exclusive with options -c and -6.

Valid values for header are:

bar

bar head and format. Used only with the -i option ( read only).

crc | CRC

ASCII header with expanded device numbers and an additional per-file checksum. There are no UID or GID restrictions associated with this header format.

odc

ASCII header with small device numbers. This is the IEEE/P1003 Data Interchange Standard cpio header and format. It has the widest range of portability of any of the header formats. It is the official format for transferring files between POSIX-conforming systems (see standards(5)). Use this format to communicate with SunOS 4 and Interactive UNIX. This header format allows UIDs and GIDs up to 262143 to be stored in the header.

tar | TAR

tar header and format. This is an older tar header format that allows UIDs and GIDs up to 2097151 to be stored in the header. It is provided for the reading of legacy archives only, that is, in conjunction with option -i.

Specifying this archive format with option -o has the same effect as specifying the “ustar” format: the output archive is in ustar format, and must be read using -Hustar.

ustar | USTAR

IEEE/P1003 Data Interchange Standard tar header and format. This header format allows UIDs and GIDs up to 2097151 to be stored in the header.

Files with UIDs and GIDs greater than the limit stated above are archived with the UID and GID of 60001. To transfer a large file (8 Gb — 1 byte), the header format can be tar|TAR, ustar|USTAR, or odc only.

-Ifile

Reads the contents of file as an input archive, instead of the standard input. 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

Attempts to skip corrupted file headers and I/O errors that might 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 can terminate prematurely. cpio finds the next good header, which can be one for a smaller archive, and terminate when the smaller archive's trailer is encountered. Use only with the -i option.

-l

In pass mode, makes hard links between the source and destination whenever possible. If the -L option is also specified, the hard link is to the file referred to by the symbolic link. Otherwise, the hard link is to the symbolic link itself. Use only with the -p option.

-L

Follows symbolic links. If a symbolic link to a directory is encountered, archives the directory referred to by the link, using the name of the link. Otherwise, archives the file referred to by the link, using the name of the link.

-m

Retains previous file modification time. This option is ineffective on directories that are being copied.

-Mmessage

Defines 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.

-Ofile

Directs the output of cpio to file, instead of the standard output. 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.

-P

Preserves ACLs. If the option is used for output, existing ACLs are written along with other attributes, except for extended attributes, to the standard output. ACLs are created as special files with a special file type. If the option is used for input, existing ACLs are extracted along with other attributes from standard input. The option recognizes the special file type. Notice that errors occurs if a cpio archive with ACLs is extracted by previous versions of cpio. This option should not be used with the -c option, as ACL support might not be present on all systems, and hence is not portable. Use ASCII headers for portability.

-r

Interactively renames files. If the user types a carriage return alone, the file is skipped. If the user types a ``.'', the original pathname is retained. Not available with cpio-p.

-Rid

Reassigns ownership and group information for each file to user ID. (ID must be a valid login ID from the passwd database.) This option is valid only when id is the invoking user or the super-user. See NOTES.

-s

Swaps bytes within each half word.

-S

Swaps halfwords within each word.

-t

Prints a table of contents of the input. If any file in the table of contents has extended attributes, these are also listed. No files are created. -t and -V are mutually exclusive.

-u

Copies unconditionally. Normally, an older file is not replaced a newer file with the same name, although an older directory updates a newer directory.

-v

Verbose. Prints a list of file and extended attribute names. When used with the -t option, the table of contents looks like the output of an ls-l command (see ls(1)).

-V

Special verbose. Prints a dot for each file read or written. Useful to assure the user that cpio is working without printing out all file names.

-6

Processes a UNIX System Sixth Edition archive format file. Use only with the -i option. This option is mutually exclusive with -c and -H.

-@

Includes extended attributes in archive. By default, cpio does not place extended attributes in the archive. With this flag, cpio looks for extended attributes on the files to be placed in the archive and add them, as regular files, to the archive. The extended attribute files go in the archive as special files with special file types. When the -@ flag is used with -i or -p, it instructs cpio to restore extended attribute data along with the normal file data. Extended attribute files can only be extracted from an archive as part of a normal file extract. Attempts to explicitly extract attribute records are ignored.

-/

Includes extended system attributes in archive. By default, cpio does not place extended system attributes in the archive. With this flag, cpio looks for extended system attributes on the files to be placed in the archive and add them, as regular files, to the archive. The extended attribute files go in the archive as special files with special file types. When the -/ flag is used with -i or -p, it instructs cpio to restore extended system attribute data along with the normal file data. Extended system attribute files can only be extracted from an archive as part of a normal file extract. Attempts to explicitly extract attribute records are ignored.

Operands

The following operands are supported:

directory

A path name of an existing directory to be used as the target of cpio-p.

pattern

Expressions making use of a pattern-matching notation similar to that used by the shell (see sh(1)) for filename pattern matching, and similar to regular expressions. The following metacharacters are defined:

*

Matches any string, including the empty string.

?

Matches any single character.

[...]

Matches any one of the enclosed characters. A pair of characters separated by `-' matches any symbol between the pair (inclusive), as defined by the system default collating sequence. If the first character following the opening `[' is a `!', the results are unspecified.

!

The ! (exclamation point) means not. For example, the !abc* pattern would exclude all files that begin with abc.

In pattern, metacharacters ?, *, and [ . . .] match the slash (/) character, and backslash (\) is an escape character. Multiple cases of pattern can be specified and if no pattern is specified, the default for pattern 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.

Usage

See largefile(5) for the description of the behavior of cpio when encountering
files greater than or equal to 2 Gbyte ( 231 bytes).

Examples

The following examples show three uses of cpio.

Example 1 Using standard input

example% ls | cpio -oc > ../newfile

When standard input is directed through a pipe to cpio-o, as
in the example above, it groups the files so they can be
directed (>) to a single file (../newfile). The -c option insures that
the file is 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.

Example 2 Extracting files into directories

example% cat newfile | cpio -icd "memo/a1" "memo/b*"

In this example, cpio-i uses the output file of cpio-o
(directed through a pipe with cat), 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.

Example 3 Copying or linking files to another directory

example% find . -depth -print | cpio -pdlmv newdir

In this example, cpio-p takes the file names piped to it
and copies or links (-l option) those files to another directory, newdir.
The -d option says to create directories as needed. The -m option says
to retain the modification time. (It is important to use the -depth
option of find(1) to generate path names for cpio. This eliminates problems that
cpio could have trying to create files under read-only directories.) The destination
directory, newdir, must exist.

Notice that when you use cpio in conjunction with find, if you
use the -L option with cpio, you must use the -follow option
with find and vice versa. Otherwise, there are undesirable results.

For multi-reel archives, dismount the old volume, mount the new one, and
continue to the next tape by typing the name of the next
device (probably the same as the first reel). To stop, type a
RETURN and cpio ends.

Environment Variables

See environ(5) for descriptions of the following environment variables that affect the
execution of cpio: LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_TIME, TZ, and NLSPATH.

TMPDIR

cpio creates its temporary file in /var/tmp by default. Otherwise, it uses the directory specified by TMPDIR.

See Also

Notes

The maximum path name length allowed in a cpio archive is determined
by the header type involved. The following table shows the proper value
for each supported archive header type.

Header type

Command line options

Maximum path name length

BINARY

“-o”

256

POSIX

“-oH
odc”

256

ASCII

“-oc”

1023

CRC

“-oH crc”

1023

USTAR

“-oH ustar”

255

When the command line options “-o-Htar” are specified, the archive
created is of type USTAR. This means that it is an error
to read this same archive using the command line options “-i-Htar”. The archive should be read using the command line options “-i-Hustar”. The options “-i-Htar” refer to an older tar
archive format.

An error message is output for files whose UID or GID are
too large to fit in the selected header format. Use -Hcrc
or -c to create archives that allow all UID or GID values.

Only the super-user can copy special files.

Blocks are reported in 512-byte quantities.

If a file has 000 permissions, contains more than 0 characters of
data, and the user is not root, the file is not saved
or restored.

When cpio is invoked in Copy In or Pass Mode by a user with
{PRIV_FILE_CHOWN_SELF} privilege, and in particular on a system where {_POSIX_CHOWN_RESTRICTED} is not
in effect (effectively granting this privilege to all users where not overridden), extracted
or copied files can end up with owners and groups determined by
those of the original archived files, which can differ from the invoking
user's. This might not be what the user intended. The -R option
can be used to retain file ownership, if desired, if you specify the
user's id.

The inode number stored in the header (/usr/include/archives.h) is an unsigned short,
which is 2 bytes. This limits the range of inode numbers from
0 to 65535. Files which are hard linked must fall in this
inode range. This could be a problem when moving cpio archives between different
vendors' machines.

You must use the same blocking factor when you retrieve or copy
files from the tape to the hard disk as you did when
you copied files from the hard disk to the tape. Therefore, you
must specify the -B or -C option.

During -p and -o processing, cpio buffers the file list presented on
stdin in a temporary file.

The new pax(1) format, with a command that supports it (for example,
tar), should be used for large files. The cpio command is no longer
part of the current POSIX standard and is deprecated in favor of
pax.