NAME

cpio - copy file archives in and out (LEGACY)

 SYNOPSIS

cpio -o[aBcv]

cpio -i[Bcdmrtuvf] [pattern ...]

cpio -p[adlmuv] directory

 DESCRIPTION

The cpio utility, depending on the options used:

• copies files to an archive file

• extracts files from an archive file

• copies files from one directory tree to another.

 OPTIONS

The cpio utility supports the XBD specification, Utility Syntax Guidelines  , except the option modifiers cannot be presented as separate arguments from the option letters.

The following options are supported:

-o

(Copy Out.) Read the standard input to obtain a list of pathnames and copy those files onto the standard output together with pathname and status information. Output is padded to a 512-byte boundary.

-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 are selected. 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 has appropriate privileges, which causes cpio to retain the owner and group of the files of the previous cpio -o. If the archive being read does not match the modifier specified, cpio may consider this to be an error and exit or may recognise the archive and continue processing. Only a user with appropriate privileges can extract block special or character special files from an archive.

-p

(Pass.) Read the standard input to obtain a list of pathnames of files that are conditionally created and copied into the destination directory tree based upon the option modifiers described below.

The following option modifiers can be appended in any sequence to the -o, -i or -p options:

a

Reset access times of input files after they have been copied. (When option l (see below) is also specified, the access times of the linked files are not reset.)

B

Block input/output 5120 bytes to the record (does not apply to the -p option; meaningful only with data directed to or from character special files).

d

Create directories as needed.

c

Write or read header information in character form for portability.

r

Interactively rename files. For each archive member matching pattern operand, a prompt will be written to the file /dev/tty. The prompt will contain the name of the archive member, but the format is otherwise unspecified. A line will then be read from /dev/tty. If this line is blank, the archive member will be skipped. If this line consists of a single period, the archive member will be processed with no modification to its name. Otherwise, its name will be replaced with the contents of the line. The cpio utility will immediately exit with a non-zero exit status if end-of-fie is encountered when reading a response, or if /dev/tty cannot be opened for reading and writing.

t

Write a table of contents of the input. No files are created.

u

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

v

Verbose: print the names of the affected files. With the t option, provides a detailed listing.

l

Whenever possible, link files rather than copying them. 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.

 OPERANDS

The following operands are supported:

directory

A pathname of an existing directory to be used as the target of cpio -p.

pattern

Expressions making use of a pattern-matching notation similar to that used by the shell for filename pattern matching, and similar to regular expressions. The following metacharacters are defined:

*

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 `!', the results are unspecified.

In pattern, the special characters "?", "*" and "[" also match the "/" character. Multiple cases of pattern can be specified and if no pattern is specified, the default for pattern is "*" (that is, select all files).

 STDIN

When the -o or -p options are used, the standard input is a text file containing a list of pathnames, one per line, to be copied.

When the -i option is used, the standard input is an archive file formatted as specified by pax with the -x cpio option.

 INPUT FILES

The files identified by the pathnames in the standard input are of any type.

When the -r option is used, the file /dev/tty is used to write prompts and read responses.

 ENVIRONMENT VARIABLES

The following environment variables may affect the execution of cpio:

LANG

Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalisation variables.

LC_COLLATE

Determine the locale for the behaviour of ranges, equivalence classes and multi-character collating elements within bracketed filename patterns.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files) and the behaviour of character classes within bracketed filename patterns (for example, '[[:lower:]]*').

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.

LC_TIME

Determine the format of date and time strings output when listing the contents of an archive with the -v option; for example:

cpio -icvt < /dev/sctmtm0

NLSPATH

Determine the location of message catalogues for the processing of LC_MESSAGES .

TZ

Determine the timezone used with date and time strings.

 ASYNCHRONOUS EVENTS

Default.

 STDOUT

When the -o option is used, the standard output is an archive file formatted as specified by pax with the -x cpio option. Otherwise, the standard output contains commentary in an unspecified format concerning the progress of the execution.

 STDERR

When the -o option is not used, the standard error contains commentary in an unspecified format concerning the progress of the execution. Otherwise, the standard error is used only for diagnostic messages.

 OUTPUT FILES

Output files are created, as specified by the archive, when the -i or -p options are used.

 EXTENDED DESCRIPTION

None.

 EXIT STATUS

The following exit values are returned:

0

Successful completion.

>0

An error occurred.

 CONSEQUENCES OF ERRORS

If a file or directory cannot be created or overwritten, cpio continues with the next file in the archive or file to be added to the archive.

 APPLICATION USAGE

Archives created by cpio are portable between XSI-conformant systems provided the same procedures are used.

The shell metacharacter notation is not fully compatible with that used by the shell and the pax utility. Not all systems support the use of the negation character [! ...] in cpio patterns. Portable applications must avoid the use of this notation.

For portable communication of data between XSI-conformant systems, it is recommended that only characters defined in the ISO/IEC 646:1991 standard International Reference Version (equivalent to ASCII) 7-bit range of characters be used and that only characters defined in the Portable Filename Character Set be used for naming files. This recommendation is given because XSI-conformant systems support diverse codesets and run in various geographical areas and there is no single, well-established codeset that incorporates all of the characters of the languages of the various geographical areas.

The cpio format only supports file sizes up to 8 gigabytes.

Applications should migrate to the pax utility.

 EXAMPLES

1. Copy the contents of a directory onto an archive:

   
   ls | cpio -oc >../cpio.out
   
   

2. Duplicate a directory hierarchy:

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

 FUTURE DIRECTIONS

None.

 SEE ALSO

ar, find, ls, pax, tar.