cpio -i [-bBcdfkmPrsStuvV6@/] [-C bufsize] [-E file]
 [-H header] [-I  [-M message]] [-R id] [pattern]...

cpio -o [-aABcLPvV@/] [-C bufsize] [-H header]
 [-O file [-M message]]

cpio -p [-adlLmPuvV@/] [-R id] directory

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.

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.

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

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 (such as the end of a diskette), 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 (/dev/rdiskette for example) and press RETURN. You might want to continue by directing cpio to use a different device. For example, if you have two floppy drives you might want to switch between them so cpio can proceed while you are changing the floppies. Press RETURN to cause the cpio process to exit.

The following options are supported: -i

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

The following operands are supported: directory

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

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.

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

The following exit values are returned: 0

See attributes(5) for descriptions of the following attributes:

ar(1), cat(1), echo(1), find(1), ls(1), pax(1), setfacl(1), sh(1), tar(1), chown(2), archives.h(3HEAD), attributes(5), environ(5), fsattr(5), largefile(5), standards(5)

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.

When the command line options "-o -H tar" 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 -H tar". The archive should be read using the command line options "-i -H ustar". The options "-i -H tar" 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 -H crc 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.