cpio - copy in and out

The cpio command has three functions:

• it copies one or more files into an archive file (Format 1)

• it retrieves files from a previously created archive (Format 2)

• it copies files into a directory (Format 3)

The cpio command has been withdrawn from the XG4 standard and replaced by the command pax.

Consequently, only the pax command should be used in the future, since cpio is now supported only for compatibility reasons.

Syntax

Format 1:	cpio -o[Bacv][ -D archive]
Format 2:	cpio -i[Bcdmrtuvf][ -D archive][ pattern...]
Format 3:	cpio -p[adlmruv] dir

Only the three main options -o, -i and -p are detailed in the descriptions of the various
formats shown above. The remaining options are listed in section “Modifiers and single options”. The various modifiers that can be used with each format are indicated in the format descriptions.

Copy files out

Format 1:

cpio -o[Bacv][ -D archive]

Modifiers

Bacv

Single option

-D archive

-o  

(o - out)
cpio reads a list of pathnames of plain files from standard input and copies these files along with some status information in a special archive format to standard output or to the archive specified with the single option -D. The archive format is the same as the one created with the command pax -x cpio, where output is padded to a 512-byte boundary. The number of 512-byte blocks copied is written by cpio to standard error.

Copy files in

Format 2:

cpio -i[Bcdmrtuvf][ -D archive][ pattern...]

Modifiers

Bcdmrtuvf

Single option

-D archive

-i

(in)

cpio reads from standard input or the archive specified with the single option -D, which is assumed to be the product of a previous cpio -o, and extracts from it only those files with names that match pattern (see below).

The extracted files are copied into the current directory tree in accordance with the specified options. The extracted files are given the same permissions as the files copied out with cpio -o. 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 -o.

Only the system administrator can extract special files.

pattern

pattern specifies the files to be selected from the archive. All shell metacharacters for file name generation can be used in defining pattern (see section “File name generation”).

If pattern is not specified, all files are extracted from the archive.

Copy files to a directory

Format 3:

cpio -p[adlmruv] dir

Additional option

adlmruv

-p

(p - pass)

cpio reads a list of pathnames of plain files and copies these files to the named directory dir in accordance with the specified options.

The number of 512-byte blocks copied by cpio is written to standard error.

dir

Name of the directory to which the files are to be copied. This directory must exist even if the -d modifier is specified.

Modifiers and single options

The following modifiers may be specified in any order. Apart from the single option -D, they must all be directly appended to the main option -o,-i or -p without intervening blanks.

a	(a - access time) Resets access times of input files after they have been copied. If the modifier l is also specified, the access times of files to which links exist are not reset.
B	(B - block) Sets an I/O block size of 512 bytes. This option is only meaningful for special files with direct access (raw devices). This modifier must not be used in combination with the main option -p.
c	(c- compatible) cpio writes or reads header information in the archive in character format for compatibility reasons.
d	(d - directory) Subdirectories are automatically created as needed.
f	Only the files not matching pattern are copied.
l	(l - link) This option must only be used in combination with option -p. It results in the creation of links to the files, instead of the files being copied.
m	(m - modification time) The original file modification times are retained. This modifier has no effect on directories. The modifiers m and a must not be specified together, since they are mutually exclusive.
r	(r - rename) Allows files to be renamed interactively on extraction. cpio prompts for a new name for each file. If you respond with a blank line (by simply pressing the Enter key), the file will not be renamed. If you respond with a dot (.), the file is copied without changing its name. Otherwise, the name of the file is changed to the text entered in response to the prompt.
t	(t - table of contents) cpio produces a table of contents of the archive. No files are copied.
u	(u - unconditional) Replaces an existing file with an extracted file even if the existing file has a more recent access date than the one being extracted. If the u modifier is not specified, the existing file is not overwritten.
v	(v - verbose) Causes cpio to display the names of the processed files. If v is used in conjunction with the modifier t, additional information on the processed files is displayed.
-D archive	archive names the archive file from which files are extracted or to which they are copied. This archive file is used instead of the standard input or standard output.

Error

Old format cannot support expanded types on file

You have not specified the -c option. Due to compatibility reasons, cpio maintains the i-nodes of files to be copied in the old format, so i-nodes exceeding 64 Kbytes can only be processed if you have specified the -c option.

directories are not being created

You did not specify the -d option in Format 2.

Locale

The following environment variables affect the execution of cpio:

LANG

Provide a default value for the internationalization variables that are unset or null. If LANG is unset of null, the corresponding value from the implementation-specific default locale will be used. If any of the internationalization variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalization variables.

LC_COLLATE

Determine the internationalized environment for the behavior of ranges, equivalence classes and multicharacter collating elements in extended regular expressions for yes/no queries.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments). LC_CTYPE governs character classes, character conversion (shifting) and the behavior of character classes in regular expressions.

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.

NLSPATH

Determine the location of message catalogs for the processing of LC_MESSAGES.

Example 1

All files in the current directory with names that begin with mb are to be copied out to an archive file named mailarchive:

$ find . -name 'mb*' -print | cpio -o -D mailarchive

15776 blocks

The find command searches the current directory for file names that begin with mb and writes all such file names to 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 the archive file mailarchive (option -D). When it has finished, cpio writes the number of copied blocks to standard error.

Example 2

List the contents of the archive file named mailarchive:

$ cpio -it -D mailarchive
mbox
mbox.new
mbox.old
15776 blocks

Example 3

The directory named dir.old is to be copied together with all its subdirectories. The duplicate directory is to be named dir.new:

$ cd dir.old
$ find . -print | cpio -pdl ../dir.new

The cd command changes the current directory to dir.old. The command find then searches this directory and all other directories below it and writes the names of all the files that it find to standard output. Since 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 (which, in this example, is at the same level in the file tree as dir.old). Subdirectories are created as needed (-d), i.e. all subdirectories of dir.old are copied recursively. Since the -l option also specified here, instead of copying the files, links are created to the files where possible.

See also

ar, cat, echo, find, ls, pax, tar