Format
cpio –o [ –aBcvyz] [–C blocksize] [–O file] [–V volpat]
cpio –i [–BbcdfmrsStuvqyz] [–C blocksize] [–I file]
[–V volpat] [pattern …]
cpio –p [–aBdlmruv] directory
The cpio utility
is fully supported for compatibility with older UNIX systems.
However, it is recommended that the pax utility
be used instead because it may provide greater functionality and is
considered the standard for portable UNIX applications
as defined by POSIX.2 IEEE standard 1003.2-1992.
Description
cpio reads
and writes files called cpio archives. A cpio archive
is a concatenation of files and directories preceded by a header giving
the filename and other file system information. With cpio,
you can create a new archive, extract contents of an existing archive,
list archive contents, and copy files from one directory to another.
Options
Every call to
cpio must
specify one and only one of the following
selector options:
- –i
- Reads an existing archive (created with the –o option)
from the standard input (stdin). Unless you specify the –t option, cpio extracts
all files matching one or more of the given pattern arguments
from the archive. Patterns are the same as those used by filename
generation (see sh). When you do not specify
a pattern argument, the default pattern * is
used; as a result, cpio extracts all files.
- –o
- Writes a new archive to the standard output (stdout), using
the list of files read from stdin. Such a list might be produced
by the ls or find commands.
For example:
ls . | cpio –o >arch
uses ls to
list the files of the working directory and then pipes this list as
input to cpio. The resulting archive contains
the contents of all the files, and is written to arch.
- –p
- Is shorthand for:
cpio –o | (cd directory; cpio –i)
where cpio –i is performed in the given
directory. You can use this option to copy entire file trees.
Consult the syntax lines to determine which
of the following additional options can be applied with a particular
selector option:
- –a
- Resets the access time (of each file accessed for copying to the
archive) to what it was before the copy took place.
- –B
- Uses buffers of 5120 bytes for input and output rather than the
default 512-byte buffers.
- –b
- Causes 16-bit words to be swapped within each longword and bytes
to be swapped within each 16-bit word of each extracted file. This
facilitates the transfer of information between different processor
architectures. This is equivalent to specifying both the –s and –S options.
- –C blocksize
- Sets the buffer size to a specified block size, rather than the
default 512-byte buffers.
- –c
- Reads and writes header information in ASCII form. Normally, cpio writes
the header information in a compact binary format. This option produces
an archive more amenable to transfer through nonbinary streams (such
as some data communication links) and is highly recommended for those
moving data between different processors.
- –d
- Forces the creation of necessary intermediate directories when
they do not already exist.
- –f
- Inverts the sense of pattern matching. More precisely, cpio extracts
a file from the archive if and only if it does not match any
of the pattern arguments.
- –I file
- Causes input to be read from the specified file, rather than from stdin.
- –l
- Gives permission to create a link to a file rather than making
a separate copy.
- –m
- Resets the modification time of an output file to the modification
time of the source file. Normally, when cpio copies
data into a file, it sets the modification time of the file to the
time at which the file is written. This option has no effect on directories.
- –O file
- Causes output to be written to the specified file, rather than
to stdout.
- –q
- Assumes all created files are text. This means that any \r (carriage
return) characters are stripped, and only the \n (newlines)
are retained.
Do not use the –q option
for converting text to a system-independent format, because that would
require all files to be read twice.
- –r
- Lets you rename files as cpio works.
When extracting, cpio displays the name
of the component it is about to extract and gives you the chance to
specify a name for the extracted file. If you enter . as
the name, cpio processes the file or directory
with no modification to the name. If you just press Enter, cpio skips
the file.
- –S
- For portability reasons, swaps pairs of 16-bit words within longwords
(a 32-bit or 64-bit word) only when extracting files. This option
does not affect the headers.
- –s
- For portability reasons, swaps pairs of bytes within each 16-bit
word only when extracting files. –s does
not affect the headers.
- –t
- Prevents files extraction, producing instead a table of filenames
contained in the archive. See the description of the –v option.
- –u
- Copies an archive file to a target file even if the target is
newer than the archive. Normally, cpio does
not copy the file.
- –V volpat
- Provides automatic
multivolume support. cpio writes output
to files, the names of which are formatted using volpat.
The current volume number replaces any occurrence of # in volpat.
When you invoke cpio with this option, it
asks for the first number in the archive set, and waits for you to
type the number and a carriage return before its precedes with the
operation. cpio issues the same sort of
message when a write error or read error occurs on the archive; the
reasoning is that this kind of error means that cpio has
reached the end of the volume and should go on to a new one.
- –v
- Provides more verbose information than usual. cpio prints
the names of files as it extracts them from or adds them to archives.
When you specify both –v and –t, cpio prints
a table of files in a format similar to that produced by the ls –l command.
- –y
- When used with –V, does not ask for
a volume number to begin with, but does ask if it gets a read or write
error.
- –z
- Performs Lempel-Ziv compression. Output
is always a 16-bit compression. On input, any compression up to 16-bit
is acceptable.
Usage notes
- Use the pax command if you need to use
multibyte patterns when searching for filenames.
- The POSIX 1003.1 standard defines formats for cpio archives
that limit the UIDs and GIDs that can be stored to the maximum value
of 262143. Values larger than this will not be properly restored.
- The byte and word swapping done by the –b, –S,
and –s options is effective only for the
file data written. With or without the –c option,
header information is always written in a machine-invariant format.
Localization
cpio uses
the following localization environment variable:
- LANG
- LC_ALL
- LC_MESSAGES
- LC_SYNTAX
- NLSPATH
See Localization for more
information.
Exit values
- 0
- Successful completion
- 1
- Failure due to any of the following:
- An incorrect option
- Incorrect command-line arguments
- Out of memory
- Compression error
- Failure on extraction
- Failure on creation
Portability
X/Open Portability Guide,
non-Berkeley UNIX systems
after Version 7.
The –q, –V, –y,
and –z options are specific to the z/OS shell.
Related information
compress, cp, dd, find, ls, mv, pax, tar, cpio, uncompress
The pax file
format description in File formats.