NAME

cpio − copy file archives in and out

SYNOPSIS

cpio -o [aABcxvCh]

cpio -i [BdcrtuxvmfPsSb6RU] [patterns]

cpio -p [aduxvlmrU] directory

DESCRIPTION

cpio -o (copy out) Read the standard input to obtain a list of path names, and copy those files to the standard output together with path name and status information.  Output is padded to a 512-byte boundary. 

cpio -i (copy in) Extract files from the standard input which is assumed to be the product of a previous cpio -o.  Only files with names that match patterns, according to the rules of Pattern Matching Notation (see regexp(5)), are selected. In addition, a leading !  within a pattern indicates that only those names should be selected that do not match the remainder of the pattern.  Multiple patterns can be specified.  If no patterns are specified, the default for patterns is * (select all files).  Extracted files are conditionally created and copied into the current directory tree, as determined by the options described below.  The permissions of the files match the permissions of the original files when the archive was created by cpio -o unless the -U option is used.  File owner and group are that of the current user unless the user has appropriate privileges, in which case cpio retains the owner and group of the files of the previous cpio -o. 

cpio -p (pass) Read the standard input to obtain a list of path names of files which are then conditionally created and copied into the destination directory tree as determined by the options described below.  Destination path names are interpreted relative to the named directory.

Options

cpio recognizes the following options in addition to -i, -o, and -p:

a Reset access times of input files after they are copied. 

A Suppress warning messages regarding optional access control list entries.  cpio(1) does not backup optional access control list entries in a file’s access control list (see acl(5)). Normally, a warning message is printed for each file that has optional access control list entries.

B Block input/output at 5120 bytes to the record (does not apply to the cpio -p option).  This option is meaningful only with data directed to or from devices that support variable-length records such as magnetic tape. 

d Create directories as needed. 

c Write or read header information in ASCII character form for portability. 

r Rename files interactively.  If the user types a null line, the file is skipped. 

t Print only a table of contents of the input.  No files are created, read, or copied. 

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

x Save or restore device special files.  Since mknod() is used to recreate these files on a restore, -ix and -px can only be used by users with appropriate privileges (see mknod(2)). This option is intended for intrasystem (backup) use only. Restoring device files onto a different system can be very dangerous.

v Verbose: cause 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)).

l Whenever possible, link files rather than copying them.  This option does not destroy existing files.  Usable only with the -p option. 

m Retain previous file modification time.  This option does not affect directories that are being copied. 

f Copy in all files except those in patterns. 

P Read a file written on a PDP-11 or VAX system (with byte swapping) that did not use the -c option.  Only useful with -i (copy in).  Files copied in this mode are not changed.  Non- ASCII files are likely to need further processing to be readable.  This processing often requires knowledge of file contents, and thus cannot always be done by this program.  ( PDP -11 and VAX are registered trademarks of Digital Equipment Corporation).  The -s, -S, and -b options below can be used when swapping all the bytes on the tape (rather than just the headers) is appropriate.  In general, text is best processed with -P and binary data with one of the other options. 

s Swap all bytes of the file.  Use only with the -i option. 

S Swap all half-words in the file.  Use only with the -i option. 

b Swap both bytes and half-words.  Use only with the -i option. 

6 Process a UNIX Sixth-Edition-format file.  Only useful with -i (copy in). 

R Resynchronize automatically when cpio goes "Out of phase," (see DIAGNOSTICS). 

C Have cpio checkpoint itself at the start of each volume.  If cpio is writing to a streaming tape drive with immediate-report mode enabled and a write error occurs, it normally aborts and exits with return code 2.  With this option specified, cpio instead automatically restarts itself from the checkpoint and rewrites the current volume.  Alternatively, if cpio is not writing to such a device and a write error occurs, cpio normally continues with the next volume.  With this option specified, however, the user can choose to either ignore the error or rewrite the current volume. 

h Follow symbolic links as though they were normal files or directories.  Normally, cpio archives the link. 

U Use the process’s file-mode creation mask (see umask(2)) to modify the mode of files created, in the same manner as creat(2).

Note that cpio archives created using a raw device file must be read using a raw device file. 

When the end of the tape is reached, cpio prompts the user for a new special file and continues. 

If you want to pass one or more metacharacters to cpio without the shell expanding them, be sure to precede each of them with a backslash (\). 

Device files written with the -ox option (such as /dev/tty03) do not transport to other implementations of HP-UX. 

EXTERNAL INFLUENCES

Environment Variables

LC_COLLATE determines the collating sequence used in evaluating pattern matching notation for file name generation. 

LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, and the characters matched by character class expressions in pattern matching notation. 

LC_TIME determines the format and content of date and time strings output when listing the contents of an archive with the -v option. 

LANG determines the language in which messages are displayed. 

If LC_COLLATE, LC_CTYPE, or LC_TIME is not specified in the environment or is set to the empty string, the value of LANG is used as a default for each unspecified or empty variable.  If LANG is not specified or is set to the empty string, a default of "C" (see lang(5)) is used instead of LANG.  If any internationalization variable contains an invalid setting, cpio behaves as if all internationalization variables are set to "C".  See environ(5).

International Code Set Support

Single- and multi-byte character code sets are supported. 

DIAGNOSTICS

The diagnostic message Out of phase indicates that cpio could not successfully read its particular “magic number” in the header.  Without the R option specified, cpio fails and returns an exit code of 2.  With the R option, cpio attempts to resync automatically (resyncing means that cpio tries to find the next good header in the archive and continues processing from there).  If cpio tries to resynchronize from being “Out of phase”, it returns an exit code of 1.  If resynchronization fails, try changing header mode (-c option) or byte swapping the header (-P or -s options). 

EXAMPLES

The first example below copies the contents of a directory into an archive; the second duplicates a directory hierarchy:

ls | cpio -o >/dev/rmt/0m

cd olddir
find .  -depth -print | cpio -pd newdir

The trivial case find . -depth -print | cpio -oB >/dev/rmt/0m can be handled more efficiently by:

find . -cpio /dev/rmt/0m

WARNINGS

Do not redirect the output of cpio to a named cpio archive file residing in the same directory as the original files belonging to that cpio archive.  This can cause loss of data. 

cpio strips any leading ./ characters in the list of filenames piped to it. 

Path names are restricted to PATH_MAX characters (see <limits.h> and limits(5)). If there are too many unique linked files, the program runs out of memory to keep track of them. Thereafter, linking information is lost. Only users with appropriate privileges can copy special files.

cpio tapes written on HP machines with the -ox[c] options can sometimes mislead (non- HP ) versions of cpio that do not support the -x option.  If a non- HP (or non- AT&T ) version of cpio happens to be modified so that ( HP ) cpio recognizes it as a device special file, a spurious device file might be created. 

If /dev/tty is not accessible, cpio issues a complaint and exits. 

The -pd option does not create the directory typed on the command line. 

The -idr option does not make empty directories. 

The -plu option does not link files to existing files. 

POSIX defines a file named TRAILER!!!  as an end-of-archive marker.  Consequently, if a file of that name is contained in a group of files being written by cpio -o, the file is interpreted as end-of-archive, and no remaining files are copied.  Recommended practice is to avoid naming files anything that resembles an end-of-archive file name. 

To create a POSIX -conforming cpio archive, the -c option must be used.  To read a POSIX -conforming cpio archive, the -c option must be used and the -b, -s, -S, and -6 options should not be used.  If the user does not have appropriate privileges, the -U option must also be used to get POSIX -conforming behavior when reading an archive.  Users with appropriate privileges should not use this option to get POSIX -conforming behavior. 

Using Cartridge Tape Drives:

The use of cpio with cartridge tape units requires additional comments.  For an explanation of the constraints on cartridge tapes, see ct(7).

Using cpio to write directly to a cartridge tape unit can severely damage the tape drive in a short amount of time, and is therefore strongly discouraged.  The recommended method of writing to the cartridge tape unit is to use tcio(1) in conjunction with cpio (note that -B must not be used when tcio(1) is used) because tcio(1) buffers data into larger pieces suitable for cartridge tapes. The -B option must be used when writing directly (that is, without using tcio(1)) to a CS/80 cartridge tape unit. 

Access Control Lists

Access control list descriptions in this entry apply only to standard HP-UX operating systems.  If HP-UX BLS software has been installed, access control lists are handled differently.  Refer to HP-UX BLS documentation for information about access control lists in the HP-UX BLS environment. 

SEE ALSO

ar(1), find(1), tar(1), tcio(1), cpio(4), acl(5), environ(5), lang(5), regexp(5). 

STANDARDS CONFORMANCE

cpio: SVID2, XPG2, XPG3

Hewlett-Packard Company  —  HP-UX Release 9.0: August 1992