NAME

cpio − copy file archives in and out

NOTICE

This entry is not identical to the corresponding entry in the HP-UX Reference.  It was modified after the manual went to print to accommodate last minute changes in the cpio command to ensure conformance to the POSIX standard.  Vertical bars in the right-hand margin identify the location of altered text. 

SYNOPSIS

cpio −o [ aABcxvCh ]

cpio −i [ BdcrtuxvmfPsSb6RU ] [ patterns ]

cpio −p [ aduxvlmrU ] directory

DESCRIPTION

Cpio −o (copy out) reads the standard input to obtain a list of path names and copies 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) extracts 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 ∗ (that is, select all files).  The extracted files are conditionally created and copied into the current directory tree based upon 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.  The owner and group of the files are that of the current user unless the user is super-user, in which case cpio retains the owner and group of the files of the previous cpio −o. 

Cpio −p (pass) reads the standard input to obtain a list of path names of files that are conditionally created and copied into the destination directory tree based upon the options described below.  Destination path names are interpreted relative to the named directory.

Options

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 having optional access control list entries.

B Block input/output at 5,120 bytes to the record (does not apply to the cpio −p option); 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 will not replace a newer file with the same name). 

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

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 is ineffective on 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 the content of the file 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 halfwords of the file.  Use only with the −i option. 

b Swap both bytes and halfwords.  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 (for example, /dev/tty03) do not transport to other implementations of HP-UX. 

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

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, and thereafter, linking information is lost. Only the super-user can copy special files.

Cpio tapes written on HP machines with the −ox[c] options might mislead (non-HP) versions of cpio that do not support the −x option.  If a non-HP (and 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 is not the super-user, the −U option must also be used to get POSIX-conforming behavior when reading an archive; the super-user should not use this option to get POSIX-conforming behavior. 

DEPENDENCIES

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

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

At and before release 2.2 on the Series 300, this system wrote a format which, when crossing media boundaries on some kinds of disks, differs from the format specified by System V.2 (although it matched that written by System III).  The program /etc/ocpio reads and writes this format and has essentially the same features as cpio except that options −S, −b and -f are omitted.  However, /etc/ocpio is considered obsolescent. 

Series 800
The −A option is not supported. 

SEE ALSO

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

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

STANDARDS CONFORMANCE

cpio: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1

Hewlett-Packard Company  —  HP-UX 7.0 (Revised)