cpio -- Copy in/out file archives

cpio –o [–aBcvyz] [–C blocksize] [–O file] [–V volpat]
cpio –i [–BbcdfmrsStuvqyz] [–C blocksize] [–I file] [–V volpat] [pattern …]
cpio –p [–aBdlmruv] directory

Purpose

cpio reads and writes files called cpio archives. A cpio archive is a concatenation of files and directories preceded by a header giving the file name and other file system information. With cpio, you can create a new archive, extract contents of an existing archive, list archive contents, and copy files from one directory to another.

Options

Every call to cpio must specify one and only one of the following selector options:
–i
Reads an existing archive (created with the –o option) from the standard input. Unless you specify the –t option, cpio extracts all files matching one or more of the given pattern arguments from the archive. Patterns are the same as those used by file name generation (see sh). When you do not specify a pattern argument, the default pattern * is used; as a result, cpio extracts all files.
–o
Writes a new archive to the standard output, using the list of files read from the standard input. Such a list might be produced by the ls or find commands. For example: 
ls . | cpio -o >arch
uses ls to list the files of the working directory and then pipes this list as input to cpio. The resulting archive contains the contents of all the files, and is written to arch.
–p
Is shorthand for: 
cpio -o | (cd directory; cpio -i)
where cpio -i is performed in the given directory. You can use this option to copy entire file trees.
Consult the syntax lines to determine which of the following additional options can be applied with a particular selector option:
–a
Resets the access time (of each file accessed for copying to the archive) to what it was before the copy took place.
–B
Uses buffers of 5120 bytes for input and output rather than the default 512-byte buffers.
–b
causes 16-bit words to be swapped within each longword and bytes to be swapped within each 16-bit word of each extracted file. This facilitates the transfer of information between different processor architectures. This is equivalent to specifying both the –s and –S options.
–C blocksize
Sets the buffer size to a specified blocksize, rather than the default 512-byte buffers.
–c
Reads and writes header information in ASCII form. Normally, cpio writes the header information in a compact binary format. This option produces an archive more amenable to transfer through nonbinary streams (such as some data communication links) and is highly recommended for those moving data between different processors.
–d
Forces the creation of necessary intermediate directories when they do not already exist.
–f
Inverts the sense of pattern matching. More precisely, cpio extracts a file from the archive if and only if it does not match any of the pattern arguments.
–I file
Causes input to be read from the specified file, rather than from stdin.
–l
Gives permission to create a link to a file rather than making a separate copy.
–m
Resets the modification time of an output file to the modification time of the source file. Normally, when cpio copies data into a file, it sets the modification time of the file to the time at which the file is written.
–O file
Causes output to be written to the specified file, rather than to stdout.
–q
Assumes all created files are text. This means that any \r (carriage return) characters are stripped, and only the \n (newlines) are retained.

It is not advisable to use the -q option for converting text to a system-independent format, since that would require all files to be read twice.

–r
Provides an interactive mechanism for selecting and renaming particular files. For each file processed, cpio displays the name before copying it to its new location. At this point, you can type in a new name for the file. If you enter an empty line, the file is skipped.
–S
For portability reasons, swaps pairs of 16-bit words within longwords (a 32-bit or 64-bit word) only when extracting files. This option does not affect the headers.
–s
For portability reasons, swaps pairs of bytes within each 16-bit word only when extracting files. –s does not affect the headers.
–t
Prevents files extraction, producing instead a table of file names contained in the archive. See the description of the –v option.
–u
Copies an archive file to a target file even if the target is newer than the archive. Normally, cpio does not copy the file.
–V volpat
Provides automatic multivolume support. cpio writes output to files, the names of which are formatted using volpat. The current volume number replaces any occurrence of # in volpat. When you invoke cpio with this option, it asks for the first number in the archive set, and waits for you to type the number and a carriage return before its precedes with the operation. cpio issues the same sort of message when a write error or read error occurs on the archive; the reasoning is that this kind of error means that cpio has reached the end of the volume and should go on to a new one.
–v
Provides more verbose information than usual. cpio prints the names of files as it extracts them from or adds them to archives. When you specify both –v and –t, cpio prints a table of files in a format similar to that produced by the ls –l command.
–y
When used with –V, does not ask for a volume number to begin with, but does ask if it gets a read or write error.
–z
Performs Lempel-Ziv compression. Output is always a 16-bit compression. On input, any compression up to 16-bit is acceptable.

File Formats

A cpio archive consists of the concatenation of one or more member files. Each member file contains a header (as described later in this command description) optionally followed by file contents (as indicated in the header). The end of the archive is indicated by another header describing an (empty) file named TRAILER!!!.

There are two types of cpio archives, differing only in the style of the header. By default, cpio writes archives with binary headers.

The information in ASCII archive headers is stored in fixed-width, octal (base 8) numbers, zero-padded on the left. Table 1 gives the order and field width for the information in the ASCII header:

Table 1. ASCII Header Format for a cpio File
Width Field Name Meaning
6 magic Magic number "070707"
6 dev Device where file resides
6 ino I-number of file
6 mode File mode
6 uid Owner user ID (UID)
6 gid Owner group ID (GID)
6 nlink Number of links to the file
6 rdev Device major or minor for a special file
11 mtime Modification time of the file
6 namesize Length of the file name
11 filesize Length of the file to follow

Most of this information is compatible with that returned by the UNIX stat function. After this information, namesize bytes of the path name is stored. namesize includes the null byte of the end of the path name. After this, filesize bytes of the file contents are recorded.

Binary headers contain the same information in 2-byte (short) and 4-byte (long) integers as shown in Table 2.

Table 2. Binary Header Format for a cpio File
Bytes Field Name Meaning
2 magic Magic number "070707"
2 dev Device where file resides
2 ino I-number of file
2 mode File mode
2 uid Owner user ID (UID)
2 gid Owner group ID (GID)
2 nlink Number of links to the file
2 rdev Device major or minor for a special file
4 mtime Modification time of the file
2 namesize Length of the file name
2 reserved Two bytes of reserved space
4 filesize Length of the file to follow

After this information comes the file name (with namesize rounded up to the nearest 2-byte boundary). Then the file contents appear as in the ASCII archive. The byte ordering of the 2- and 4-byte integers in the binary format is machine-dependent, and thus portability of this format is not easily guaranteed.

Compressed cpio archives are exactly equivalent to the corresponding archive being passed to a 16-bit compress utility.

Usage Notes

  1. The byte and word swapping done by the –b, –S, and –s options is effective only for the file data written. With or without the –c option, header information is always written in a machine-invariant format.
  2. The cpio utility is scheduled to be withdrawn from XPG; for standards compatibility, you should use pax.

Exit Values

Possible exit status values are:
0
Successful completion.
1
Failure due to any of the following:
  • An incorrect option
  • Incorrect command-line arguments
  • Out of memory
  • Compression error
  • Failure on extraction
  • Failure on creation

Portability

X/Open Portability Guide, non-Berkeley UNIX systems after Version 7.

The –q, –V, –y, and –z options are specific to the OpenExtensions shell.

Related Commands

cp, dd, find, ls, mv, pax, tar