CPIO(1) User Commands CPIO(1)

NAME

cpio - copy file archives in and out

SYNOPSIS

cpio -i [-bBcdfkmPqrsStuvV6@/] [-C bufsize] [-E file]
[-H header] [-I [-M message]] [-R id] [pattern]...


cpio -o [-aABcLPqvV@/] [-C bufsize] [-H header]
[-O file [-M message]]


cpio -p [-adlLmPquvV@/] [-R id] directory

DESCRIPTION

The cpio command copies files into and out of a cpio archive. The
cpio archive can span multiple volumes. The -i, -o, and -p options
select the action to be performed. The following list describes each
of the actions. These actions are mutually exclusive.

Copy In Mode

cpio -i (copy in) extracts files from the standard input, which is
assumed to be the product of a previous cpio -o command. Only files
with names that match one of the patterns are selected. See sh(1) and
OPERANDS for more information about pattern. Extracted files are
conditionally copied into the current directory tree, based on the
options described below. The permissions of the files are those of
the previous cpio -o command. The owner and group are the same as the
current user, unless the current user has the {PRIV_FILE_CHOWN_SELF}
privilege. See chown(2). If this is the case, owner and group are the
same as those resulting from the previous cpio -o command. Notice
that if cpio -i tries to create a file that already exists and the
existing file is the same age or younger (newer), cpio outputs a
warning message and not replace the file. The -u option can be used
to unconditionally overwrite the existing file.

Copy Out Mode

cpio -o (copy out) reads a list of file path names from the standard
input and copies those files to the standard output, together with
path name and status information in the form of a cpio archive.
Output is padded to an 8192-byte boundary by default or to the user-
specified block size (with the -B or -C options) or to some device-
dependent block size where necessary (as with the CTC tape).

Pass Mode

cpio -p (pass) reads a list of file path names from the standard
input and conditionally copies those files into the destination
directory tree, based on the options described below.


If the underlying file system of the source file supports detection
of holes as reported by pathconf(2), the file is a sparse file, and
the destination file is seekable, then holes in sparse files are
preserved in pass mode, otherwise holes are filled with zeros.


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 are not used, cpio
prints the following message:

To continue, type device/file name when ready.


To continue, you must replace the medium and type the character
special device name (/dev/rdiskette for example) and press RETURN.
You might want to continue by directing cpio to use a different
device. For example, if you have two floppy drives you might want to
switch between them so cpio can proceed while you are changing the
floppies. Press RETURN to cause the cpio process to exit.

OPTIONS

The following options are supported:

-i
(copy in) Reads an archive from the standard input and
conditionally extracts the files contained in it and places
them into the current directory tree.


-o
(copy out) Reads a list of file path names from the standard
input and copies those files to the standard output in the form
of a cpio archive.


-p
(pass) Reads a list of file path names from the standard input
and conditionally copies those files into the destination
directory tree.


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

-a
Resets access times of input files after they have been
copied, making cpio's access invisible. Access times
are not reset for linked files when cpio -pla is
specified.


-A
Appends 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.
The effect on files that are linked in the existing
portion of the archive is unpredictable.


-b
Reverses the order of the bytes within each word. Use
only with the -i option.


-B
Blocks input/output 5120 bytes to the record. The
default buffer size is 8192 bytes when this and the -C
options are not used. -B does not apply to the -p
(pass) option.


-c
Reads or writes header information in ASCII character
form for portability. There are no UID or GID
restrictions associated with this header format. Use
this option between SVR4-based machines, or the -H odc
option between unknown machines. The -c option implies
the use of expanded device numbers, which are only
supported on SVR4-based systems. When transferring
files between SunOS 4 or Interactive UNIX and the
Solaris 2.6 Operating environment or compatible
versions, use -H odc.


-C bufsize
Blocks input/output bufsize bytes to the record, where
bufsize is replaced by a positive integer. The default
buffer size is 8192 bytes when this and -B options are
not used. -C does not apply to the -p (pass) option.


-d
Creates directories as needed.


-E file
Specifies an input file (file) that contains a list of
filenames to be extracted from the archive (one
filename per line).


-f
Copies in all files except those in patterns. See
OPERANDS for a description of pattern.


-H header
Reads or writes header information in header format.
Always use this option or the -c option when the origin
and the destination machines are different types. This
option is mutually exclusive with options -c and -6.

Valid values for header are:

bar
bar head and format. Used only with
the -i option (read only).


crc | CRC
ASCII header with expanded device
numbers and an additional per-file
checksum. There are no UID or GID
restrictions associated with this
header format.


odc
ASCII header with small device
numbers. This is the IEEE/P1003 Data
Interchange Standard cpio header and
format. It has the widest range of
portability of any of the header
formats. It is the official format for
transferring files between POSIX-
conforming systems (see standards(7)).
Use this format to communicate with
SunOS 4 and Interactive UNIX. This
header format allows UIDs and GIDs up
to 262143 to be stored in the header.


tar | TAR
tar header and format. This is an
older tar header format that allows
UIDs and GIDs up to 2097151 to be
stored in the header. It is provided
for the reading of legacy archives
only, that is, in conjunction with
option -i.

Specifying this archive format with
option -o has the same effect as
specifying the "ustar" format: the
output archive is in ustar format, and
must be read using -H ustar.


ustar | USTAR
IEEE/P1003 Data Interchange Standard
tar header and format. This header
format allows UIDs and GIDs up to
2097151 to be stored in the header.

Files with UIDs and GIDs greater than the limit stated
above are archived with the UID and GID of 60001. To
transfer a large file (8 Gb - 1 byte), the header
format can be tar|TAR, ustar|USTAR, or odc only.


-I file
Reads the contents of file as an input archive, instead
of the standard input. 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
Attempts to skip corrupted file headers and I/O errors
that might 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 can
terminate prematurely. cpio finds the next good header,
which can be one for a smaller archive, and terminate
when the smaller archive's trailer is encountered. Use
only with the -i option.


-l
In pass mode, makes hard links between the source and
destination whenever possible. If the -L option is also
specified, the hard link is to the file referred to by
the symbolic link. Otherwise, the hard link is to the
symbolic link itself. Use only with the -p option.


-L
Follows symbolic links. If a symbolic link to a
directory is encountered, archives the directory
referred to by the link, using the name of the link.
Otherwise, archives the file referred to by the link,
using the name of the link.


-m
Retains previous file modification time. This option is
ineffective on directories that are being copied.


-M message
Defines 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.


-O file
Directs the output of cpio to file, instead of the
standard output. 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.


-P
Preserves ACLs. If the option is used for output,
existing ACLs are written along with other attributes,
except for extended attributes, to the standard output.
ACLs are created as special files with a special file
type. If the option is used for input, existing ACLs
are extracted along with other attributes from standard
input. The option recognizes the special file type.
Notice that errors occurs if a cpio archive with ACLs
is extracted by previous versions of cpio. This option
should not be used with the -c option, as ACL support
might not be present on all systems, and hence is not
portable. Use ASCII headers for portability.


-q
Quiet. Suppresses the number of blocks message that
normally is printed after the copy is completed.


-r
Interactively renames files. If the user types a
carriage return alone, the file is skipped. If the user
types a ``.'', the original pathname is retained. Not
available with cpio -p.


-R id
Reassigns ownership and group information for each file
to user ID. (ID must be a valid login ID from the
passwd database.) This option is valid only when id is
the invoking user or the super-user. See NOTES.


-s
Swaps bytes within each half word.


-S
Swaps halfwords within each word.


-t
Prints a table of contents of the input. If any file in
the table of contents has extended attributes, these
are also listed. No files are created. -t and -V are
mutually exclusive.


-u
Copies unconditionally. Normally, an older file is not
replaced a newer file with the same name, although an
older directory updates a newer directory.


-v
Verbose. Prints a list of file and extended attribute
names. When used with the -t option, the table of
contents looks like the output of an ls -l command (see
ls(1)).


-V
Special verbose. Prints a dot for each file read or
written. Useful to assure the user that cpio is working
without printing out all file names.


-6
Processes a UNIX System Sixth Edition archive format
file. Use only with the -i option. This option is
mutually exclusive with -c and -H.


-@
Includes extended attributes in archive. By default,
cpio does not place extended attributes in the archive.
With this flag, cpio looks for extended attributes on
the files to be placed in the archive and add them, as
regular files, to the archive. The extended attribute
files go in the archive as special files with special
file types. When the -@ flag is used with -i or -p, it
instructs cpio to restore extended attribute data along
with the normal file data. Extended attribute files can
only be extracted from an archive as part of a normal
file extract. Attempts to explicitly extract attribute
records are ignored.


-/
Includes extended system attributes in archive. By
default, cpio does not place extended system attributes
in the archive. With this flag, cpio looks for extended
system attributes on the files to be placed in the
archive and add them, as regular files, to the archive.
The extended attribute files go in the archive as
special files with special file types. When the -/ flag
is used with -i or -p, it instructs cpio to restore
extended system attribute data along with the normal
file data. Extended system attribute files can only be
extracted from an archive as part of a normal file
extract. Attempts to explicitly extract attribute
records are ignored.

OPERANDS

The following operands are supported:

directory
A path name 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 (see sh(1)) 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.


!
The ! (exclamation point) means not. For
example, the !abc* pattern would exclude all
files that begin with abc.

In pattern, metacharacters ?, *, and [...] match the
slash (/) character, and backslash (\) is an escape
character. Multiple cases of pattern can be specified
and if no pattern is specified, the default for pattern
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.

USAGE

See largefile(7) for the description of the behavior of cpio when
encountering files greater than or equal to 2 Gbyte (2^31 bytes).

EXAMPLES

The following examples show three uses of cpio.

Example 1: Using standard input

example% ls | cpio -oc > ../newfile


When standard input is directed through a pipe to cpio -o, as in the
example above, it groups the files so they can be directed (>) to a
single file (../newfile). The -c option insures that the file is
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 direct the output to a device
instead of a file.

Example 2: Extracting files into directories

example% cat newfile | cpio -icd "memo/a1" "memo/b*"


In this example, cpio -i uses the output file of cpio -o (directed
through a pipe with cat), 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 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.

Example 3: Copying or linking files to another directory

example% find . -depth -print | cpio -pdlmv newdir


In this example, cpio -p takes the file names piped to it and copies
or links (-l option) those files to another directory, newdir. The -d
option says to create directories as needed. The -m option says to
retain the modification time. (It is important to use the -depth
option of find(1) to generate path names for cpio. This eliminates
problems that cpio could have trying to create files under read-only
directories.) The destination directory, newdir, must exist.


Notice that when you use cpio in conjunction with find, if you use
the -L option with cpio, you must use the -follow option with find
and vice versa. Otherwise, there are undesirable results.


For multi-reel archives, dismount the old volume, mount the new one,
and continue to the next tape by typing the name of the next device
(probably the same as the first reel). To stop, type a RETURN and
cpio ends.

ENVIRONMENT VARIABLES

See environ(7) for descriptions of the following environment
variables that affect the execution of cpio: LC_COLLATE, LC_CTYPE,
LC_MESSAGES, LC_TIME, TZ, and NLSPATH.

TMPDIR
cpio creates its temporary file in /var/tmp by default.
Otherwise, it uses the directory specified by TMPDIR.

EXIT STATUS

The following exit values are returned:

0
Successful completion.


>0
An error occurred.

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|CSI | Enabled |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+

SEE ALSO

ar(1), cat(1), echo(1), find(1), ls(1), pax(1), setfacl(1), sh(1),
tar(1), chown(2), archives.h(3HEAD), attributes(7), environ(7),
fsattr(7), largefile(7), standards(7)

NOTES

The maximum path name length allowed in a cpio archive is determined
by the header type involved. The following table shows the proper
value for each supported archive header type.


Header type Command line options Maximum path name length
BINARY "-o" 256
POSIX "-oH odc" 256
ASCII "-oc" 1023
CRC "-oH crc" 1023
USTAR "-oH ustar" 255


When the command line options "-o -H tar" are specified, the archive
created is of type USTAR. This means that it is an error to read this
same archive using the command line options "-i -H tar". The archive
should be read using the command line options "-i -H ustar". The
options "-i -H tar" refer to an older tar archive format.


An error message is output for files whose UID or GID are too large
to fit in the selected header format. Use -H crc or -c to create
archives that allow all UID or GID values.


Only the super-user can copy special files.


Blocks are reported in 512-byte quantities.


If a file has 000 permissions, contains more than 0 characters of
data, and the user is not root, the file is not saved or restored.


When cpio is invoked in Copy In or Pass Mode by a user with
{PRIV_FILE_CHOWN_SELF} privilege, and in particular on a system where
{_POSIX_CHOWN_RESTRICTED} is not in effect (effectively granting this
privilege to all users where not overridden), extracted or copied
files can end up with owners and groups determined by those of the
original archived files, which can differ from the invoking user's.
This might not be what the user intended. The -R option can be used
to retain file ownership, if desired, if you specify the user's id.


The inode number stored in the header (/usr/include/archives.h) is an
unsigned short, which is 2 bytes. This limits the range of inode
numbers from 0 to 65535. Files which are hard linked must fall in
this inode range. This could be a problem when moving cpio archives
between different vendors' machines.


You must use the same blocking factor when you retrieve or copy files
from the tape to the hard disk as you did when you copied files from
the hard disk to the tape. Therefore, you must specify the -B or -C
option.


During -p and -o processing, cpio buffers the file list presented on
stdin in a temporary file.


The new pax(1) format, with a command that supports it (for example,
tar), should be used for large files. The cpio command is no longer
part of the current POSIX standard and is deprecated in favor of pax.

February 17, 2023 CPIO(1)