NAME

cpio − copy file archives in and out

SYNOPSIS

cpio −o [ aBcxv ]

cpio −i [ BdcrtuxvmfPsSb6R ] [ patterns ]

cpio −p [ aduxvlm ] directory

DESCRIPTION

Cpio −o (copy out) reads the standard input to obtain a list of path names and copies those files onto 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 are selected.  Patterns are given in the name-generating notation of sh(1). In patterns, meta-characters ?, ∗, and [...] match the slash / character.  Multiple patterns may be specified and if no patterns are specified, the default for patterns is ∗ (i.e., 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 will be those of the previous cpio −o.  The owner and group of the files will be that of the current user unless the user is super-user, which causes cpio to retain 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.

The meanings of the available options are:

a Reset access times of input files after they have been copied. 

B Input/output is to be blocked 5,120 bytes to the record (does not apply to the pass option); meaningful only with data directed to or from devices which support variable length records such as magnetic tape. 

d Create directories as needed. 

c Write header information in ASCII character form for portability. 

r Interactively rename files.  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.  Mknod(2) will be used to recreate these files on a restore, and thus −ix 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:  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)).

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 will probably 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 gets "Out of phase," (see DIAGNOSTICS). 

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 will prompt the user for a new special file and continue. 

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 (e.g., /dev/tty03) will not transport to other implementations of HP-UX. 

HARDWARE 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).  Tcio(1) buffers data into larger pieces suitable for cartridge tapes. 

The −B option must be used when writing directly (i.e., without using tcio(1)) to a CS-80 cartridge tape unit. 

At and before release 4.0 on the 500 and 2.2 on the 200 and 300, these systems 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 will read and write 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 500:
All files with inodes greater than or equal to 65535 are unlinkable with the −i option.  A separate copy of each file is made instead. 

The number of blocks reported by cpio is always in units of 512-byte blocks, regardless of the block size of the initialized media. 

Note that the −B option must not be used when performing raw I/O to the internal miniature flexible disk drive (HP 9130K), if the I/O requires more than one volume. 

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

SEE ALSO

ar(1), find(1), tar(1), tcio(1), cpio(4). 

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 will fail and return exit code 2.  With the R option, cpio will try resyncing 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 will return exit code 1.  If resynchronization fails, try changing header mode (c option) or byte swapping the header (P or s options). 

WARNING

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

BUGS

Path names are restricted to 256 characters.  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 can mislead (non-HP) versions of cpio which 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 could be created. 

If /dev/tty is not accessible, cpio issues a complaint, or refuses to work. 

The −pd option will not create the directory typed on the command line. 

The −idr option will not make empty directories. 

The −plu option will not link files to existing files. 

Cpio will fail while restoring files from a backup tape (cpio −i) if the following conditions are met:

your working directory during the restore is not the root directory (/),
and the files being restored have multiple links,
and their path names begin with slash (/). 

If these conditions are met, the following occurs:

(1) The first file on the backup tape is restored correctly;

(2) The second file is removed, and the restore fails. 

Note that the second file is removed before the restore fails! 

Cpio then writes the message "Cannot link file1 & file2" to stderr, but also writes "file1 linked to file2" on stdout, as if everything went fine.  The correct message is that written to stderr. 

There are two work-arounds for this bug, either of which will solve the problem.  The first is to make sure that your working directory is the root directory during the restore process.  The second is to use relative file names (path names not beginning with slash) in your backup. 

INTERNATIONAL SUPPORT

8- and 16-bit data, 8-bit filenames. 

Hewlett-Packard Company  —  Version B.1,  May 11, 2021