cpio(1)

cpio -- copy file archives in and out

Synopsis

   cpio -i [ bBcdfkmrsSTtuvV6 ] [-C bufsize ] [ -E file ] [ -G file ] [ -H hdr ]
   	[ -e [xattr_name=]action[,[xattr_name=]action ...]
   	[ -I file [-M message] ] [-R ID] ] [ pattern ...]
   
   cpio -o [ aABcLvV ] [ -C bufsize] [-G file] [-H hdr ] [ -K mediasize ]
   	[ -e [xattr_name=]action[,[xattr_name=]action ... ]
   	[ -O file [-M message] ]
   

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

Description

The -i, -o, and -p options select the action to be performed. The following list describes each of the actions (which are mutually exclusive).

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(1). 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 file system type (vxfs) file system 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(5)). In regular expressions, pattern searches are performed on characters, not bytes, as described on sh(1). 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

Append 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. Always use this option (or the -H option) when the origin and the destination machines are different types (mutually exclusive with -H and -6). (The -c option implies expanded fundamental types. See ``Notices'' for more information.)

This option (or -H hdr) must be specified if the file to be copied in or out is larger than 2GB.

-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:

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

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.

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

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

-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(1)); dates are displayed according to the locale specified in the LC_TIME environment variable (see LANG on environ(5)).

-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(1), you could use find(1), echo(1), cat(1), 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(1) 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 codes

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

Files

/usr/lib/locale/locale/LC_MESSAGES/uxcore.abi: language-specific message file. (See LANG on environ(5).)

References

ar(1), archives(4), cat(1), echo(1), find(1), ls(1), tar(1)

Notices

Support for large files

The cpio(1) 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 cpio will not be able to extract files larger than 2GB in size.

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.

Compatibility with earlier releases

Versions of cpio on earlier releases of UnixWare used a slightly different syntax for the -e option (that is, [-e extent_opt]). In these earlier releases, the -e option applied only to Veritas file system type (vxfs) extent attributes. For compatibility with these earlier releases, if an action is specified with the -e option, but without a preceding xattr_name=, that action is assumed by cpio to apply to the vxfs_extent attribute only.

An archive created with the -c option on a System V Release 4 system cannot be read on System V Release 3.2 systems, or earlier. Use the -H odc option, which is equivalent to the header created by the -c option in earlier System V Releases, if the cpio image will be read by a pre-System V Release 4 version of cpio.

In releases of UNIX System V prior to Release 4, symbolic links are not understood. The result of copying in a symbolic link on an older release will be a regular file that contains the pathname of the referenced file.

Prior to Release 4, the default buffer size was 512 bytes. Beginning with Release 4, the default buffer size is optimized for the device and using the -C option to specify a different block size may cause cpio to fail. Therefore, care must be taken when choosing the block size. To avoid wasting space on streaming tape drives, use the -C option and specify an appropriate block size.

Using variable-length block mode when writing magnetic tapes is discouraged because it may not work correctly in releases before SVR4.2 MP. Magnetic tape should always be written in fixed-length block mode, even though you are free to change the default fixed-block length from 512 bytes to any other fixed-block mode the tape drive supports.

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