cpio(C)

cpio -- copy file archives in and out

Syntax

cpio -i [ AbBcdfkmqrsSTtuvV6 ] [-C bufsize ]
[ -E file ] [ -G file ] [ -H hdr ]
[ -e [xattr_name=]action[,[xattr_name=]action ...]
[ [ -I file [, file ... ] ] [ -M message ] [-N]
[ -Pifd,ofd ] [-R ID] ] [ pattern ...]

cpio -o [ aABcLvV ] [ -C bufsize] [-G file] [-H hdr ]
[ [ -I file [, file ... ] ] [ -K mediasize ]
[ -e [xattr_name=]action[,[xattr_name=]action ... ]
[ -O file [-M message] ] [ -Pifd,ofd ]

cpio -p directory |[adlLmuvV] [-R ID]
[-e [xattr_name=]action[,[xattr_name=]action ...]
[ -Pifd,ofd ]

Description

cpio copies files to and from an archive file or another directory hierarchy.

There are three main options to cpio which determine its mode of operation. These modes are used to create an archive (cpio -o), extract files from an archive (cpio -i), and copy files from one filesystem to another (cpio -p). There are a number of secondary options, which are interpreted differently depending on which mode of operation cpio is in. The following list describes each of the actions (which are mutually exclusive) in more detail.

cpio -i (copy in) extracts files from the standard input (only if -I is not specified), which is assumed to be the product of a previous cpio -o. Only files with names that match patterns are selected. patterns are regular expressions given in the filename-generating notation of sh(C). In patterns, meta-characters ``?'', ``*'', and ``[ . . . ]'' match the slash (``/'') character, and backslash (``\'') is an escape character. A ``!'' meta-character means not. (For example, the ``!abc*'' pattern would exclude all files that begin with ``abc''.) Multiple patterns may be specified and if no patterns are specified, the default for patterns 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. Extracted files are conditionally created and copied into the current directory tree based on the options described below.

The permissions of the files will be those of the previous cpio -o. Owner and group permissions will be the same as the current user unless the current user possesses the owner privilege. If this is true, owner and group permissions will be the same as those resulting from the previous cpio -o.

NOTE: If cpio -i tries to create a file that already exists and the existing file is the same age or younger (newer), cpio will output a warning message and not replace the file.

(The -u option can be used to overwrite, unconditionally, the existing file.) If file names are given as absolute pathnames to cpio -o, then when the files are restored via cpio -i, they will be written to their original directories regardless of the current directory. This behavior can be circumvented by using the -r option. When cpio is invoked from the shell, each pattern should be quoted.

In normal circumstances, cpio sets the Hdr_type variable (which defines the header type) to NONE before checking the actual header type. It does this even if you have specified a different header type on the command line. When you use the -k option, however, cpio does not set Hdr_type to NONE if you've specified a header type on the command line (with the -c or -H option). In this case, cpio sets Hdr_type to the header type you've specified. Thus you have a way of making sure the correct header file type is specified, which improves your chances of recovering files correctly. For this reason, we recommend you specify the header type for the file (with -c or -H) whenever you use the -k option.

cpio -o (copy out) reads the standard input to obtain a list of pathnames and copies those files onto the standard output (only if the -O is not specified) together with pathname and status information.

cpio -p (pass) reads the standard input to obtain a list of pathnames of files that are conditionally created and copied into the destination directory tree based on the options described below.

By default, cpio also attempts to copy extended attribute information on the source to the target. Extended attribute information includes:

Access Control Lists (ACLs)
Privileges
Veritas filesystem type (vxfs) filesystem attributes

The cpio command issues a warning if existing extended attribute information on the source cannot be copied to the destination (unless other actions are specified for extended attributes via the -e option).

cpio processes supplementary code set characters, and recognizes supplementary code set characters in the message given to the -M option (see below) according to the locale specified in the LC_CTYPE environment variable (see LANG on environ(M)). In regular expressions, pattern searches are performed on characters, not bytes, as described on sh(C). Under the -vt option (see below), the date is displayed according to the locale specified in the LC_TIME environment variable.

The meanings of the available options are

-a

Reset access times of input files after they have been copied. Access times are not reset for linked files when cpio -pla is specified.

-A

When used with cpio -i, suppresses absolute filenames. A leading ``/'' character is removed from the filename during copy-in. If a pattern is provided, it should match the relative (rather than the absolute) pathname.

When used with cpio -o, appends files to an archive. The -A option requires the -O option. Valid only with archives that are files, or that are on floppy diskettes or hard disk partitions.

-b

Reverse the order of the bytes within each word. (Use only with the -i option.)

-B

Input/output is to be blocked 5120 bytes to the record. The default buffer size is device dependent when neither this nor the -C option is used.

-c

Read or write header information in ASCII character form for portability, with support for expanded fundamental types. Always use this option (or the -H option) when the origin and the destination machines are different types (mutually exclusive with -H and -6). Specifying -c is equivalent to specifying -H newc. To obtain the equivalent behavior for -c supported on previous releases, specify -H odc. This option (or -H hdr) must be specified if the file to be copied in or out is larger than 2GB. See ``Notices'' for more information.

-C bufsize

Input/output is to be blocked bufsize bytes to the record, where bufsize is replaced by a positive integer. The default buffer size is device dependent when neither this nor the -B option is used. If used with -K, bufsize must be a multiple of 1K.

-d

Directories are to be created as needed.

-E file

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

[-e [xattr_name=]action[,[xattr_name=]action . . .]

Specify how to handle various extended file attributes. The following are the valid parameters for xattr_name and the extended attribute information to which they refer:

ACL

Access Control Lists (ACLs) on the source files and directories.

priv

Privileges on the source files and directories

vxfs_extent

Extent attributes include reserved space, a fixed extent size, and extent alignment. It may not be possible to preserve the information if the destination file system does not support extent attributes, has a different block size than the source file system, or lacks free extents appropriate to satisfy the extent attribute requirements.

unknown

Can be used only on restore (cpio -i), and specifies how to deal with extended file attributes not recognized by the current version of cpio.

all

Refers to all extended attribute information for each file or directory processed.

Valid values for action are:

warn: Issue a warning message if extent attribute information cannot be kept (default).
force: Fail the file save or restore or copy if extent attribute information cannot be kept.
ignore: Ignore extent attribute information entirely.

For more information on extended attributes, see ``Notices''.

-f

Copy in all files except those in patterns (See the paragraph about cpio -i for a description of patterns.)

-G file

NOTE: This option is intended for use by front-end or application programs that invoke cpio. If you're running cpio at the shell level, you probably won't need this option.

The -G option allows a program to specify file as the interface through which cpio communicates with a user. Specifically, this interface is used for end-of-medium processing (but it also affects where -r gets done); it is used both for writing the prompts to the user and for reading the user's input. By default, /dev/tty is the interface. However, in some situations (such as graphics application environments), /dev/tty is not available. Therefore an alternative interface, such as a pseudo-tty, may be needed.

If the argument to -G is the keyword STDIO, it will print prompts (to change the media, and also for new file names when the -r option is used) on stdout, and read responses from stdin.

-H hdr

Read or write header information in hdr format. Always use this option or the -c option when the origin and the destination machines are different types (mutually exclusive with -c and -6). Valid values for hdr are:

bin: (binary format) This is a non-portable version of the -c header format.
crc or CRC: ASCII header with expanded fundamental types and an additional per-file checksum. See ``Notices'' for details.
The crc file format has been updated to handle files larger than 2GB.
newc: (new character format without checksum) Write archives using the SVR4 extended ASCII header format.
ustar or USTAR: IEEE/P1003 Data Interchange Standard header and format
tar or TAR: tar header and format
odc: ASCII header with small fundamental types (see NOTICES)

-I file[, file ... ]

Read the contents of file as an input archive. 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. This option does not work if file is a regular file.

-k

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

-K mediasize

Specify the media size as a multiple of 1K. If used with -C bufsize, then bufsize must be a multiple of 1K. Use only with the -o option.

-l

Whenever possible (only with the -p option), link files rather than copying them. (Even if a file cannot be linked, it will be copied.)

-L

Follow symbolic links. The default is not to follow symbolic links.

-m

Retain previous file modification time. The modification time and access time of a restored file is set to the modification time of the file when it was backed up. Modification time of directories is not retained.

-M message

Define 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. message may contain supplementary code set characters.

-N

Invokes "safe mode" (-i only). cpio is restricted to writing files in the current working directory or below. Can be specified with -i only.

-O file

Direct the output of cpio to file. 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. Using this option with -o guarantees exclusive access to the character special device or output file. Redirecting output to a device or file does not guarantee exclusive access and could result in a corrupted archive if a second process opens the device or file while the first process is still active. Also see ``Compatibility with earlier releases''.

-r

Interactively rename files. If the user types a carriage return alone, the file is skipped. If the user types a ``.'' the original pathname will be retained. (Should be used only with cpio -i.)

-R ID

Reassign ownership and group information for each file to user ID (ID must be a valid login ID from /etc/passwd). This option is valid only for a privileged user.

-s

Swap bytes within each half word.

-S

Swap halfwords within each word.

-t

Print a table of contents of the input. No files are created (mutually exclusive with -V).

-T

Truncate long file names to 14 characters. Use only with the -i option.

-u

Copy unconditionally (normally, an older file will not replace a newer file with the same name).

-v

Verbose: causes a list of file names to be printed. When used with the -t option, the table of contents looks like the output of an ls -l command (see ls(C)); dates are displayed according to the locale specified in the LC_TIME environment variable (see LANG on environ(M)). Also see ``Compatibility with earlier releases''.

-V

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

-6

Process a UNIX System Sixth Edition archive format file. Use only with the -i option (mutually exclusive with -c and -H).

NOTE: 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 aren't used, cpio will print the following message:

   End of medium on input (output). To continue, type device/file name when ready.

To continue, you must replace the medium and type the character special device name (/dev/rdsk/f0 for example) and press <Return>. You may want to continue by directing cpio to use a different device. For example, if you have two floppy drives you may want to switch between them so cpio can proceed while you are changing the floppies.

Usage

Output (-o)

When standard input is directed through a pipe to cpio -o, files are grouped so they can be redirected (>) to a single file (../newfile). The -c option insures that the file will be portable to other machines (as would the -H option). Instead of ls(C), you could use find(C), echo(C), cat(C), and so on, to pipe a list of names to cpio. You could redirect the output to a device instead of a file.

   ls | cpio -oc > ../newfile

Input (-i)

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

   cat newfile | cpio -ickd "memo/a1" "memo/b*"

Pass (-p)

cpio -p takes the file names piped to it and copies or links (-l option) those files to another directory (newdir in the example below). The -d option allows you to create directories as needed. The -m option lets you retain the modification time and security level. (It is important to use the -depth option of find(C) to generate pathnames for cpio. Use of this option eliminates problems cpio could have in trying to create files under read-only directories.) The destination directory, newdir, must exist.

   find . -depth -print | cpio -pdlmv newdir

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

Exit values

1: usage error
2: file error (but cpio completes, displaying error number)
3: fatal error (cpio dies immediately)

Reading from magnetic tape in any fixed-length block length besides the block length that the media was written in originally will cause an I/O error. If you want to read a tape that was written using a block-length besides the default of 512, you must use the tapecntl(C) command ( qv ) to either set the block-length of the drive to match the block length of the media or to set the drive into variable block length mode.

Notices

Support for large files

The cpio(C) utility supports the archival of files larger than 2 gigabytes (2GB) in size when using the ASCII (-c) or CRC (-H crc) formats. Files up to 2^63-1 bytes in size are supported. Previous versions of Release 5 cpio can not extract files larger than 2GB in size.

Compatibility with earlier releases

Earlier versions of cpio always printed a list of archived filenames to stderr. The current behavior is to print the file list ot stderr if the -O option is not specified, and to stdout if -O is specified.
The Release 5.0.7 version of cpio is included for backward compatibility, located in the /osr5/usr/bin directory. Note that this version of cpio cannot handle files larger than 2GB and is not able to access the 32-bit device nodes used in this release. This means that /osr5/usr/bin/cpio cannot successfully backup and restore the /dev directory.
The default archive format generated by /bin/cpio does not support inode numbers greater than 65535. To archive files with inode numbers greater than 65535, specify another archive format using the -c or -H hdr options.
There are differences in the default buffer size that cpio uses in the absence of the -B or -C options.
When using the expanded ASCII format (-c, -H newc or -H crc options), the default SVR5 version of cpio (/bin/cpio) defers archiving an inode's data until it sees the last hard link to it or EOF. /bin/cpio then writes the headers of the links seen previously with their filesizes set to zero. It follows these with the inode data for the last link. When restoring from such an archive, /bin/cpio may create a read-only directory before attempting to write file data in that directory. This will be unsuccessful unless you are root; using the -depth option to find does not help in these circumstances.
The /osr5/usr/bin/cpio version of cpio overcomes this problem by writing the same file data for each hard link. When restoring from an archive, it recreates the hard links so they reference a single inode. If you use the SVR5 /bin/cpio to restore from an archive created using /osr5/usr/bin/cpio, each link points to a separate copy of the original inode.
The default SVR5 version of cpio (/bin/cpio) treats linked file differently than the OSR5 /osr5/usr/bin/cpio version, as explained above, in order to save space in archives. This has the side effect of being unable to extract the second or subsequent links to a file without extracting the file itself. In other words, if two files are linked, and then archived using /bin/cpio, you cannot extract only the second filename from the archive; an error like the one in the example below is retuned:
```
   # cpio -iv -I tm file2
   UX:cpio: WARNING: Cannot link "file1" and "file2":  No such file or directory
```
The OSR5 version of cpio (/osr5/usr/bin/cpio ) avoids this problem by storing the entire file contents for each link. This has the potential to make cpio archives with lots of linked files larger than those created using /bin/cpio, but does permit any linked version of a file to be extracted even if the first link name is not extracted.
-I file[, file ... only works when file is a device, not a regular file. For the same effect with regular files, use:
```
   # cat file1 file2 ... | cpio -i
```
The -n option, which was used to calculate the checksum value for each file read from an archive, is no longer supported.
The format of the table-of-contents listing that is generated by cpio -itv is somewhat different.

Restoring extended attributes

If you attempt to restore a cpio archive that contains extended attribute information and the version of cpio being used does not support one or more extended attributes found in the archive, the following occurs:

1.: The extended attributes not supported by the version of cpio being used will not be restored. It is assumed that if you use a version of cpio that does not support extended attributes, the target file system probably does not support extended attributes either.
2.: cpio creates a file in /tmp with a name of the form ._xAtTr_n where n is an apparently arbitrary number. If you use the -v option of cpio, the verbose output of cpio will contain references to this file. This file, which is not likely to be very large, can either be removed manually or it will be removed with the other files in /tmp during the next system reboot.

Pathnames restrictions

Pathnames are restricted to 256 characters for the binary (the default) and -H odc header formats. Otherwise, pathnames are restricted to 1024 characters.

Expanded fundamental types support

The default binary header format and the ODC header format do not support expanded fundamental types (EFTs). Smaller, preSVR4-type sizes are assumed by these header formats. If you are trying to use cpio over file systems with EFT and one of these two header formats are used, you will get the error message Old format cannot support expanded types. Use the -c or the -Hcrc options instead. See archives(4) for details on type sizes.

Copying block or character special files

Only a privileged user can copy block or character special files.

When attempting to redirect standard input or standard output from or to a block or character special device you may get an error message such as Cannot read from device or Cannot write to device. The appearance of such a message does not necessarily mean a true I/O error has occurred. It is more likely to mean the user does not have access to that device; the user should ask the system administrator to allocate the device for him or her.

It is not desirable for device overwriting to be the ordinary behavior for cpio even when the -u option is specified. This has been done for system resilience. If a device on an archive being read in does not match a device that is already on the system, it is almost always the case that the device on the archive is different because the archive was exported from another system that had different device numbers. To overwrite existing devices in such a situation could be crippling to the system, depending on which devices are overwritten and what the change is.

Block sizes

Blocks are reported in 512-byte quantities.

The st01 tape driver does not always require block sizes that are in multiples of 512 bytes, but block size is device dependent. Use tapecntl to set the tape driver to use the block size supported by the tape device. Failure to set the block size correctly will result in an error when the driver attempts to write a block of the unsupported size.

Saving and restoring files with 000 permissions

If a file has ``000'' permissions and contains more than 0 characters of data, and the user does not have the appropriate privilege, the file will not be saved or restored.

Matching tape block length on read

Reading from magnetic tape in any fixed-length block length, besides the block length that the media was written in originally, will cause an I/O error. In order to read a tape that was written using some block length besides the default of 512, use the tapecntl(1) command (qv) to either set the block length of the drive to match the block length of the media, or to set the drive into variable block length mode.

Environment variables

If POSIX2 is set in the current environment, then the pattern-matching notation specified by POSIX.2 is used:

*: 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 `!', it is regarded as a not operator; the characters within the braces are not used in the pattern.

In pattern, the special characters ``?'', ``*'' and ``['' also match the / character. Multiple cases of pattern can be specified and if no pattern is specified, ``*'' is used (that is, all files are selected).