---

CPIO (1)

---

cpio - copy file archives in and out

CONTENTS

Synopsis
Description
Examples
Environment Variables
See Also
Diagnostics
Notes

cpio -i[bcdfkmrstuvBSV6] [-C size] [-E file] [-H hdr] [[-I file] [-M msg]] [-R id] [patterns]

cpio -o[acvABLPV] [-C size] [-H hdr] [[-M msg] [-O file]]

cpio -p[adlmPuvLV] [-R id] directory

Cpio creates and extracts file archives and copies files.

With the -i option, cpio works in 'copy-in' mode and extracts files from a file archive. By default, the archive is read from standard input. Optional arguments are interpreted as patterns and restrict the set of extracted files to those matching any of the patterns. A '!' at the beginning of the pattern selects all files that do not match this pattern. The syntax is otherwise identical to that described in glob(7), except that the slash character '/' is matched by meta-character constructs with '*', '?' and '['. Care must be taken to quote meta-characters appropriately from the shell. File permissions are set to those in the archive; if the caller is the super-user, ownerships are restored as well. Cpio will not create directories, preserve modification times or overwrite more recently modified target files unless the appropriate -d, -m or -u options are specified. Archives compressed with bzip2(1), compress(1), gzip(1), or rpm(1) are transparently decompressed on input.

With -o, cpio works in 'copy-out' mode, creates archives and writes them to standard output per default. A list of filenames to be included in the archive is read from standard input; if the name of a directory appears, it is included in the archive, but cpio will not include any of its members unless they are explicitly given in addition. The find(1) utility is useful to generate a list of files (see also its -cpio and -ncpio operators). When producing a filename list for cpio, find should always be invoked with -depth since this makes it possible to extract write-protected directories for users other than the super-user.

The -p option selects 'pass' mode; a list of files is read from standard input as described for -o; files are copied to the specified directory, preserving attributes as described for -i. Special files are re-created in the target hierarchy, and hard links between copied files are preserved.

When a premature end-of-file is detected with -i and -o and the archive is a block or character special file, the user is prompted for new media.

The following options alter the behavior of cpio:

-a	Resets the access times of files that were included in the archive with -o or copied with -p.
-A	Append files to the archive. The archive must be seekable, such as a regular file or a block device, or a tape device capable of writing between filemarks.
-b	Swap bytes within each half word and half words within each word of input file data.
-B	Blocks input and output archives at 5120 byte records. The default blocking size is device dependent.
-c	Specifies that archive headers are in SVR4 ASCII cpio format. This option is ignored with -i unless the -k option is also present.
-C size	Blocks input and output archives at size byte records.
-d	Creates missing parent directories for each file extracted from the archive and allows the extraction of directories.
-E file	Each line read from file is taken as a pattern in addition to those specified on the command line.
-f	Reverses the sense of patterns such that a file that does not match any of the patterns is selected.
-H header
	Specifies the archive header format to be one of: crc SVR4 ASCII cpio format with checksum; sco SCO UnixWare 7.1 ASCII cpio format; scocrc SCO UnixWare 7.1 ASCII cpio format with checksum; odc traditional ASCII cpio format, as standardized in IEEE Std. 1003.1, 1996; bbs byte-swapped binary cpio format; sgi SGI IRIX extended binary cpio format; cray Cray UNICOS 9 cpio format; cray5 Cray UNICOS 5 cpio format; dec Digital UNIX extended cpio format; tar tar format; otar old tar format; ustar IEEE Std. 1003.1, 1996 tar format; pax[:option,[option,...]] IEEE Std. 1003.1, 2001 pax format. Format-specific options are: linkdata For a regular file which has multiple hard links, the file data is stored once for each link in the archive, instead of being stored for the first entry only. This option must be used with care since many implementations are unable to read the resulting archive. times Causes the times of last access and last modification of each archived file to be stored in an extended pax header. This in particular allows the time of last access to be restored when the archive is read. sun Sun Solaris 7 extended tar format; gnu GNU tar format; bar SunOS 4 bar format; zip[:cc] zip format with optional compression method. If cc is one of en (normal, default), ex (extra), ef (fast), or es (super fast), the standard deflate compression is used. e0 selects no compression, and bz2 selects bzip2 compression. This option is ignored with -i unless the -k option is also present. The default for -o is binary cpio format.
-I file	Selects a file that is read with the -i option instead of standard input.
-k	Try to continue operation on read errors and invalid headers. If an archive contains another archive, files from either archive may be chosen.
-l	Link files instead of copying them with -p if possible.
-L	Follow symbolic links when reading files with -o or -p.
-m	Restore modification times of extracted files to those given in the archive.
-M message
	The given message is printed instead of the standard one with -I or -O when changing media.
-O file	Selects an archive file that is written instead of standard output with the -o option.
-P	In copy-out or pass mode, interpret the data read from standard input as prototype lines of colon-separated fields of the form type:user:group:mode:atime:mtime:major:minor:path For each non-empty field, the corresponding attribute of the input file is overridden. With this option, an unprivileged user can create an archive that contains files with arbitrary attributes. The meanings of the individual fields are: type File type, one of: b (block device), c (character device), d (directory), f (plain file), p (named pipe), or s (symbolic link). user The owner of the file, which can be a numeric user ID or a user name. group The group owner of the file, which can be a numeric group ID or a group name. mode The octal mode of the file. atime The time the file was last accessed. Note that most archive formats cannot store this attribute, in which case it is ignored. The format is the same as that of the mtime field. mtime The time the file was last modified. This is either a decimal integer specifying the seconds past the epoch, or an ISO 8601 date and time field of the format YYYYMMDDTHHMMSS, e.g. 20070326T190511, the latter being relative to the current time zone and with all digits past the T being optional. major minor   Major and minor device numbers as with mknod(1M). These fields are only allowed for block and character devices. path The name of the file to be archived. If the file is not a symbolic link, and the specification is otherwise sufficient, the file needs not exist at the time the archive is created. A non-existent regular file will be empty in the archive.
	This option is an extension.
-r	Rename files interactively. Before a file is extracted from the archive, its file name is printed on standard error and the user is prompted to specify a substitute file name. If the line read from the terminal is empty, the file is skipped; if the line consists of a single dot, the name is retained; otherwise, the line forms the new file name.
-R user	Set the ownership of extracted files to the user and group ids of user instead of those specified in the archive. Valid only for the super-user.
-s	Swap bytes within each half word of input file data.
-S	Swap half words within each word of input file data.
-t	When combined with the -o option, a list of files in the archive is written to standard output; no files are extracted.
-u	Cpio will overwrite existing target files that were modified more recently than the file in the archive when this option is given.
-v	Prints the file names of archived or extracted files with -i and -o and a verbose output format with -t. If given twice (-vv) in combination with -t when reading a zip archive, information about compression level and method is printed.
-V	Prints a dot for each archived or extracted file.
-6	Selects Unix 6th Edition archive format (only in copy-in mode).

Characteristics of archive formats are as follows:

	maximum user/group id	maximum file size	maximum pathname length	bits in dev_t (major/minor)
binary	65535	2 GB	256	16
-H sgi	65535	9 EB	256	14/18
-H odc	262143	8 GB	256	18
-H dec	262143	8 GB	256	24/24
-c, -H crc	4.3e9	4 GB	1024	32/32
-H sco, -H scocrc	4.3e9	9 EB	1024	32/32
-H cray, -H cray5	1.8e19	9 EB	65535	64
-H otar	2097151	8 GB	99	n/a
-H tar, -H ustar	2097151	8 GB	256 (99)	21/21
-H pax	1.8e19	9 EB	65535	21/21
-H sun	1.8e19	9 EB	65535	63/63
-H gnu	1.8e19	9 EB	65535	63/63
-H bar	2097151	8 GB	427	21
-H zip	4.3e9	9 EB	60000	32

By default, binary cpio archives are written. The byte order of such archives depends on the machine on which the archive is created. Unlike some other implementations, cpio fully supports archives of either byte order. -H bbs can be used to create an archive with the byte order opposed to that of the current machine.

The sgi format extends the binary format to handle larger files and more device bits. If an archive does not contain any entries that actually need the extensions, it is identical to a binary archive. -H sgi archives are always created in MSB order.

The odc format was introduced with System III and standardized with IEEE Std. 1003.1. All known cpio implementations since around 1980 can read this format.

The dec format extends the odc format to support more device bits. Archives in this format are generally incompatible with odc archives and need special implementation support to be read.

The -c format was introduced with System V Release 4. Except for the file size, it imposes no practical limitations on files archived. The original SVR4 implementation stores the contents of hard linked files only once and with the last archived link. This cpio ensures compatibility with SVR4. With archives created by implementations that employ other methods for storing hard linked files, each file is extracted as a single link, and some of these files may be empty. Implementations that expect methods other than the original SVR4 one may extract no data for hard linked files at all.

The crc format is essentially the same as the -c format but adds a simple checksum (not a CRC, despite its name) for the data of regular files. The checksum requires the implementation to read each file twice, which can considerably increase running time and system overhead. As not all implementations claiming to support this format handle the checksum correctly, it is of limited use.

The sco and scocrc formats are variants of the -c and -H crc formats, respectively, with extensions to support larger files. The extensions result in a different archive format only if files larger than slightly below 2 GB occur.

The cray format extends all header fields to 64 bits. It thus imposes no practical limitations of any kind on archived files, but requires special implementation support to be read. Although it is originally a binary format, the byte order is always MSB as on Cray machines. The cray5 format is an older variant that was used with UNICOS 5 and earlier.

The otar format was introduced with the Unix 7th Edition tar utility. Archives in this format can be read on all Unix systems since about 1980. It can only hold regular files (and, on more recent systems, symbolic links). For file names that contain characters with the most significant bit set (non-ASCII characters), implementations differ in the interpretation of the header checksum.

The ustar format was introduced with IEEE Std. 1003.1. It extends the old tar format with support for directories, device files, and longer file names. Pathnames of single-linked files can consist of up to 256 characters, dependent on the position of slashes. Files with multiple links can only be archived if the first link encountered is no longer than 100 characters. Due to implementation errors, file names longer than 99 characters can not considered to be generally portable. Another addition of the ustar format are fields for the symbolic user and group IDs. These fields are created by cpio, but ignored when reading such archives.

With -H tar, a variant of the ustar format is selected which stores file type bits in the mode field to work around common implementation problems. These bits are ignored by cpio when reading archives.

The pax format is an extension to the ustar format. If attributes cannot be archived with ustar, an extended header is written. Unless the size of an entry is greater than 8 GB, a pax archive should be readable by any implementation capable of reading ustar archives, although files may be extracted under wrong names and extended headers may be extracted as separate files. If a file name contains non-UTF-8 characters, it may not be archived or extracted correctly because of a problem of the pax format specification.

The sun format extends the ustar format similar as the pax format does. The extended headers in sun format archives are not understood by implementations that support only the pax format and vice-versa. The sun format has also problems with non-UTF-8 characters in file names.

The GNU tar format is mostly compatible with the other tar formats, unless an archive entry actually uses its extended features. There are no practical limitations on files archived with this format. The implementation of cpio is limited to expanded numerical fields and long file names; in particular, there is no support for sparse files or incremental backups. If cpio creates a multi-volume GNU archive, it just splits a single-volume archive in multiple parts, as with the other formats; GNU multi-volume archives are not supported.

The bar format is similar to the tar format, but can store longer file names. It requires special implementation support to be read.

The zip format can be read in many non-Unix environments. There are several restrictions on archives intended for data exchange: only regular files should be stored; file times, permissions and ownerships might be ignored by other implementations; there should be no more than 65536 files in the archive; the total archive size should not exceed 2 GB; only deflate compression should be used. Otherwise, cpio stores all information available with other archive formats in extended zip file headers, so if archive portability is of no concern, the zip implementation in cpio can archive complete Unix file hierarchies. Cpio supports the zip64 format extension for large files; it automatically writes zip64 entries if necessary. Cpio can extract all known zip format compression codes. It does not support zip encryption. Multi-volume zip archives are created as splitted single-volume archives, as with the other formats written by cpio; generic multi-volume zip archives are not supported.

Extract all files named Makefile or makefile from the archive stored on /dev/rmt/c0s0, overwriting recent files:

cpio -idmu -I /dev/rmt/c0s0 '[Mm]akefile' '*/[Mm]akefile'

List the files contained in a software distribution archive:

cpio -itv -I distribution.tar.gz

Write a gzip(1) compressed ustar archive containing all files below the directory project to the file project.tar.gz, excluding all directories named CVS or SCCS and their contents:

find project -depth -print | egrep -v '/(CVS|SCCS)(/|$)' |
  cpio -o -H ustar | gzip -c > project.tar.gz

Copy the directory work and its contents to the directory savedfiles:

find work -depth -print | cpio -pdm savedfiles

Self-extracting zip archives are not automatically recognized, but can normally be read using the -k option, as with

cpio -itvk -H zip -I archive.exe

LANG, LC_ALL
	See locale(7).
LC_CTYPE
	Selects the mapping of bytes to characters used for matching patterns.
LC_TIME
	Sets the month names printed with -tv.
SYSV3	If this variable is set, the -c option has the same effect as -H odc; -H newc can be used to select SVR4 ASCII format. The output format of -tv is changed, as well as the text of diagnostic messages.

find(1), pax(1), tar(1)

Cpio exits with

0	after successful operation;
1	on usage errors;
2	when operation was continued after minor errors;
3	on fatal error conditions.

Device and inode numbers are used for hard link recognition with the various cpio formats. Since the header space cannot hold large numbers present in current file systems, devices and inode numbers are set on a per-archive basis. This enables hard link recognition with all cpio formats, but the link connection to files appended with -A is not preserved.

If a numeric user or group id does not fit within the size of the header field in the selected format, files are stored with the user id (or group id, respectively) set to 60001.

Use of the -A option with a zip format archive may cause data loss if the archive was not previously created by cpio itself.

Cpio cannot store file names that contain newline characters; see the NOTES section of find(1) for more information.

If the file names passed to cpio -o begin with a slash character, absolute path names are stored in the archive and will be extracted to these path names later regardless of the current working directory. This is normally not advisable, and relative path names should be passed to cpio only.