path: root/tools/cpio/src/cpio.1

'\" t
.\" Copyright (c) 2003 Gunnar Ritter
.\"
.\" This software is provided 'as-is', without any express or implied
.\" warranty. In no event will the authors be held liable for any damages
.\" arising from the use of this software.
.\"
.\" Permission is granted to anyone to use this software for any purpose,
.\" including commercial applications, and to alter it and redistribute
.\" it freely, subject to the following restrictions:
.\"
.\" 1. The origin of this software must not be misrepresented; you must not
.\"    claim that you wrote the original software. If you use this software
.\"    in a product, an acknowledgment in the product documentation would be
.\"    appreciated but is not required.
.\"
.\" 2. Altered source versions must be plainly marked as such, and must not be
.\"    misrepresented as being the original software.
.\"
.\" 3. This notice may not be removed or altered from any source distribution.
.\" Sccsid @(#)cpio.1	1.92 (gritter) 3/26/07
.TH CPIO 1 "3/26/07" "Heirloom Toolchest" "User Commands"
.SH NAME
cpio \- copy file archives in and out
.SH SYNOPSIS
.PD 0
.HP
.nh
.ad l
\fBcpio\fR \fB\-i\fR[\fBbcdfkmrstuvBSV6\fR] [\fB\-C\fI\ size\fR]
[\fB\-E\fI\ file\fR] [\fB\-H\fI\ hdr\fR] [[\fB\-I\fI\ file\fR]
[\fB\-M\fI\ msg\fR]] [\fB\-R\fI\ id\fR] [\fIpatterns\fR]
.HP
.ad l
\fBcpio\fR \fB\-o\fR[\fBacvABLPV\fR] [\fB\-C\fI\ size\fR]
[\fB\-H\fI\ hdr\fR] [[\fB\-M\fI\ msg\fR] [\fB\-O\fI\ file\fR]]
.HP
.ad l
\fBcpio\fR \fB\-p\fR[\fBadlmPuvLV\fR] [\fB\-R\fI\ id\fR] \fIdirectory\fR
.br
.PD
.ad b
.hy 1
.SH DESCRIPTION
.I Cpio
creates and extracts file archives and copies files.
.PP
With the
.B \-i
option,
.I cpio
works in
.RI ` copy-in '
mode and extracts files from a file archive.
By default,
the archive is read from standard input.
Optional arguments are interpreted as
.I patterns
and restrict the set of extracted files
to those matching any of the
.IR patterns .
A
.RB ` !\& '
at the beginning of the
.I pattern
selects all files that do not match this
.IR pattern .
The syntax is otherwise identical to that described in
.IR glob (7),
except that the slash character
.RB ` / '
is matched by
meta-character constructs with
.RB ` * ',
.RB ` ? '
and
.RB ` [ '.
Care must be taken to quote meta-characters appropriately from the shell.
File permissions are set to those in the archive;
if the caller is the super-user,
ownerships are restored as well.
.I Cpio
will not create directories,
preserve modification times
or overwrite more recently modified target files
unless the appropriate
.IR \-d ,
.I \-m
or
.I \-u
options are specified.
Archives compressed with
.IR bzip2 (1),
.IR compress (1),
.IR gzip (1),
or
.IR rpm (1)
are transparently de\%compressed on input.
.PP
With
.BR \-o ,
.I cpio
works in
.RI ` copy-out '
mode,
creates archives
and writes them to standard output per default.
A list of filenames to be included in the archive is
read from standard input;
if the name of a directory appears,
it is included in the archive,
but
.I cpio
will not include any of its members
unless they are explicitly given in addition.
The
.IR find (1)
utility is useful to generate a list of files
(see also its
.I \-cpio
and
.I \-ncpio
operators).
When producing a filename list for
.IR cpio ,
find should always be invoked with
.I \-depth
since this makes it possible to extract write-protected directories
for users other than the super-user.
.PP
The
.B \-p
option selects
.RI ` pass '
mode;
a list of files is read from standard input as described for
.IR \-o ;
files are copied to the specified
.IR directory ,
preserving attributes as described for
.IR \-i .
Special files are re-created in the target hierarchy,
and hard links between copied files are preserved.
.PP
When a premature end-of-file is detected with
.I \-i
and
.I \-o
and the archive is a block or character special file,
the user is prompted for new media.
.PP
The following options alter the behavior of
.IR cpio :
.TP
.B \-a
Resets the access times of files
that were included in the archive with
.I \-o
or copied with
.IR \-p .
.TP
.B \-A
Append files to the archive.
The archive must be seekable,
such as a regular file or a block device,
or a tape device capable of writing between filemarks.
.TP
.B \-b
Swap bytes within each half word
and half words within each word
of input file data.
.TP
.B \-B
Blocks input and output archives at 5120 byte records.
The default blocking size is device dependent.
.TP
.B \-c
Specifies that archive headers are in SVR4 ASCII cpio format.
This option is ignored with
.I \-i
unless the
.I \-k
option is also present.
.TP
\fB\-C\fI size\fR
Blocks input and output archives at
.I size
byte records.
.TP
.B \-d
Creates missing parent directories
for each file extracted from the archive
and allows the extraction of directories.
.TP
\fB\-E\fI file\fR
Each line read from
.I file
is taken as a pattern in addition
to those specified on the command line.
.TP
.B \-f
Reverses the sense of patterns
such that a file that does not match any of the patterns
is selected.
.TP
\fB\-H\fI header\fR
Specifies the archive header format to be one of:
.sp
.in +6
.TS
lfB l.
\fBcrc\fR	SVR4 ASCII cpio format with checksum;\ 
\fBsco\fR	T{
SCO UnixWare 7.1 ASCII cpio format;
T}
\fBscocrc\fR	T{
SCO UnixWare 7.1 ASCII cpio format with checksum;
T}
\fBodc\fR	T{
traditional ASCII cpio format, as standardized in IEEE Std. 1003.1, 1996;
T}
\fBbbs\fR	byte-swapped binary cpio format;
\fBsgi\fR	T{
SGI IRIX extended binary cpio format;
T}
\fBcray\fR	T{
Cray UNICOS 9 cpio format;
T}
\fBcray5\fR	T{
Cray UNICOS 5 cpio format;
T}
\fBdec\fR	T{
Digital UNIX extended cpio format;
T}
\fBtar\fR	tar format;
\fBotar\fR	old tar format;
\fBustar\fR	T{
IEEE Std. 1003.1, 1996 tar format;
T}
.T&
l s.
\fBpax\fR[\fB:\fIoption\fB,\fR[\fIoption\fB,\fR\|...]]
.T&
l l.
\&	T{
IEEE Std. 1003.1, 2001 pax format.
Format-specific \fIoptions\fR are:
.in +2n
.ti 0
.br
\fBlinkdata\fR
.br
For a regular file which has multiple hard links,
the file data is stored once for each link in the archive,
instead of being stored for the first entry only.
This option must be used with care
since many implementations are unable
to read the resulting archive.
.ti 0
.br
\fBtimes\fR
.br
Causes the times of last access and last modification
of each archived file
to be stored in an extended \fIpax\fR header.
This in particular allows the time of last access
to be restored when the archive is read.
.br
.in -2n
T}
\fBsun\fR	T{
Sun Solaris 7 extended tar format;
T}
\fBgnu\fR	T{
GNU tar format;
T}
\fBbar\fR	T{
SunOS 4 bar format;
T}
\fBzip\fR[\fB:\fIcc\fR]	T{
zip format with optional compression method.
If \fIcc\fR is one of
\fBen\fR (normal, default),
\fBex\fR (extra),
\fBef\fR (fast),
or
\fBes\fR (super fast),
the standard \fIdeflate\fR compression is used.
\fBe0\fR selects no compression,
and
\fBbz2\fR selects \fIbzip2\fR compression.
T}
.TE
.in -6
.sp
This option is ignored with
.I \-i
unless the
.I \-k
option is also present.
The default for
.I \-o
is binary cpio format.
.TP
\fB\-I\fI\ file\fR
Selects a
.I file
that is read with the
.I \-i
option instead of standard input.
.TP
.B \-k
Try to continue operation on read errors and invalid headers.
If an archive contains another archive,
files from either archive may be chosen.
.TP
.B \-l
Link files instead of copying them with
.I \-p
if possible.
.TP
.B \-L
Follow symbolic links when reading files with
.I \-o
or
.IR \-p .
.TP
.B \-m
Restore modification times of extracted files
to those given in the archive.
.TP
\fB\-M\fI message\fR
The given
.I message
is printed instead of the standard one
with
.I \-I
or
.I \-O
when changing media.
.TP
\fB\-O\fI file\fR
Selects an archive
.I file
that is written instead of standard output
with the
.I \-o
option.
.TP
.B \-P
In copy-out or pass mode,
interpret the data read from standard input
as prototype lines
of colon-separated fields
of the form
.in +3m
.sp
\fItype\fB:\fIuser\fB:\fIgroup\fB:\fImode\fB:\fIatime\fB:\fImtime\fB:\fImajor\fB:\fIminor\fB:\fIpath\fR
.sp
.in -3m
For each non-empty field,
the corresponding attribute of the input file is overridden.
With this option,
an unprivileged user can create
an archive that contains files
with arbitrary attributes.
The meanings of the individual fields are:
.RS
.TP 6
.PD 0
.I type
File type, one of:
\fBb\fR (block device),
\fBc\fR (character device),
\fBd\fR (directory),
\fBf\fR (plain file),
\fBp\fR (named pipe),
or
\fBs\fR (symbolic link).
.TP
.I user
The owner of the file,
which can be a numeric user ID or a user name.
.TP
.I group
The group owner of the file,
which can be a numeric group ID or a group name.
.TP
.I mode
The octal mode of the file.
.TP
.I atime
The time the file was last accessed.
Note that most archive formats cannot store this attribute,
in which case it is ignored.
The format is the same as that of the
.I mtime
field.
.TP
.I mtime
The time the file was last modified.
This is either a decimal integer
specifying the seconds past the epoch,
or an ISO\ 8601 date and time field
of the format \fIYYYYMMDD\fBT\fIHHMMSS\fR,
e.g. 20070326T190511,
the latter being relative to the current time zone
and with all digits past the \fBT\fR being optional.
.TP
.I major minor
Major and minor device numbers as with
.IR mknod (1M).
These fields are only allowed for block and character devices.
.TP
.I path
The name of the file to be archived.
If the file is not a symbolic link,
and the specification is otherwise sufficient,
the file needs not exist
at the time the archive is created.
A non-existent regular file will be empty in the archive.
.PD
.RE
.IP
This option is an extension.
.TP
.B \-r
Rename files interactively.
Before a file is extracted from the archive,
its file name is printed on standard error
and the user is prompted to specify a substitute file name.
If the line read from the terminal is empty,
the file is skipped;
if the line consists of a single dot,
the name is retained;
otherwise,
the line forms the new file name.
.TP
\fB\-R\fI user\fR
Set the ownership of extracted files
to the user and group ids of
.I user
instead of those specified in the archive.
Valid only for the super-user.
.TP
.B \-s
Swap bytes within each half word
of input file data.
.TP
.B \-S
Swap half words within each word
of input file data.
.TP
.B \-t
When combined with the
.I \-o
option,
a list of files in the archive is written to standard output;
no files are extracted.
.TP
.B \-u
.I Cpio
will overwrite existing target files
that were modified more recently than the file in the archive
when this option is given.
.TP
.B \-v
Prints the file names of archived or extracted files with
.I \-i
and
.I \-o
and a verbose output format with
.IR \-t .
If given twice
.RB ( \-vv )
in combination with
.I \-t
when reading a
.I zip
archive,
information about compression level and method is printed.
.TP
.B \-V
Prints a dot for each archived or extracted file.
.TP
.B \-6
Selects Unix 6th Edition archive format
(only in copy-in mode).
.PP
.ne 37
Characteristics of archive formats are as follows:
.sp
.TS
allbox;
l r r r l
l1fB r2 n2 r2 c.
	T{
.ad l
maximum user/\%group id
T}	T{
.ad l
maximum file size
T}	T{
.ad l
maximum pathname length
T}	T{
.ad l
bits in dev_t (major/minor)
T}
binary	65535	2 GB\ 	256	\ 16
\-H\ sgi	65535	9 EB\ 	256	\ 14/18
\-H\ odc	262143	8 GB\ 	256	\ 18
\-H\ dec	262143	8 GB\ 	256	\ 24/24
T{
\-c, \-H\ crc
T}	4.3e9	4 GB\ 	1024	\ 32/32
T{
\-H\ sco, \-H\ scocrc
T}	4.3e9	9 EB\ 	1024	\ 32/32
T{
\-H\ cray, \-H\ cray5
T}	1.8e19	9 EB\ 	65535	\ 64
\-H\ otar	2097151	8 GB\ 	99	\ n/a
T{
\-H\ tar,
\-H\ ustar
T}	2097151	8 GB\ 	256 (99)	\ 21/21
\-H\ pax	1.8e19	9 EB\ 	65535	\ 21/21
\-H\ sun	1.8e19	9 EB\ 	65535	\ 63/63
\-H\ gnu	1.8e19	9 EB\ 	65535	\ 63/63
\-H\ bar	2097151	8 GB\ 	427	\ 21
\-H\ zip	4.3e9	9 EB\ 	60000	\ 32
.TE
.sp
.PP
By default,
.B binary
cpio archives are written.
The byte order of such archives
depends on the machine
on which the archive is created.
Unlike some other implementations,
.I cpio
fully supports
archives of either byte order.
.I \-H\ bbs
can be used to create an archive
with the byte order opposed to that of the current machine.
.PP
The
.B sgi
format extends the binary format
to handle larger files and more device bits.
If an archive does not contain any entries
that actually need the extensions,
it is identical to a binary archive.
.I \-H\ sgi
archives are always created in MSB order.
.PP
The
.B odc
format was introduced with System\ III
and standardized with IEEE Std. 1003.1.
All known
.I cpio
implementations since around 1980 can read this format.
.PP
The
.B dec
format extends the
.I odc
format
to support more device bits.
Archives in this format are generally incompatible with
.I odc
archives
and need special implementation support to be read.
.PP
The
.B \-c
format was introduced with System\ V Release\ 4.
Except for the file size,
it imposes no practical limitations
on files archived.
The original SVR4 implementation
stores the contents of hard linked files
only once and with the last archived link.
This
.I cpio
ensures compatibility with SVR4.
With archives created by implementations that employ other methods
for storing hard linked files,
each file is extracted as a single link,
and some of these files may be empty.
Implementations that expect methods other than the original SVR4 one
may extract no data for hard linked files at all.
.PP
The
.B crc
format is essentially the same as the
.I \-c
format
but adds a simple checksum (not a CRC, despite its name)
for the data of regular files.
The checksum requires the implementation to read each file twice,
which can considerably increase running time and system overhead.
As not all implementations claiming to support this format
handle the checksum correctly,
it is of limited use.
.PP
The
.B sco
and
.B scocrc
formats are variants of the
.I \-c
and
.I \-H\ crc
formats, respectively,
with extensions to support larger files.
The extensions result in a different archive format
only if files larger than slightly below 2\ GB occur.
.PP
The
.B cray
format extends all header fields to 64 bits.
It thus imposes no practical limitations of any kind
on archived files,
but requires special implementation support
to be read.
Although it is originally a binary format,
the byte order is always MSB as on Cray machines.
The
.B cray5
format is an older variant
that was used with UNICOS 5 and earlier.
.PP
The
.B otar
format was introduced with the Unix 7th Edition
.I tar
utility.
Archives in this format
can be read on all Unix systems since about 1980.
It can only hold regular files
(and, on more recent systems, symbolic links).
For file names that contain characters with the most significant bit set
(non-ASCII characters),
implementations differ in the interpretation of the header checksum.
.PP
The
.B ustar
format was introduced with IEEE Std. 1003.1.
It extends the old
.I tar
format
with support for directories, device files,
and longer file names.
Pathnames of single-linked files can consist of up to 256 characters,
dependent on the position of slashes.
Files with multiple links can only be archived
if the first link encountered is no longer than 100 characters.
Due to implementation errors,
file names longer than 99 characters
can not considered to be generally portable.
Another addition of the
.I ustar
format
are fields for the symbolic user and group IDs.
These fields are created by
.IR cpio ,
but ignored when reading such archives.
.PP
With
.BR "\-H tar" ,
a variant of the
.I ustar
format is selected
which stores file type bits in the mode field
to work around common implementation problems.
These bits are ignored by
.I cpio
when reading archives.
.PP
The
.B pax
format is an extension to the
.I ustar
format.
If attributes cannot be archived with
.IR ustar ,
an extended header is written.
Unless the size of an entry is greater than 8\ GB,
a
.I pax
archive should be readable by any implementation
capable of reading
.I ustar
archives,
although files may be extracted under wrong names
and extended headers may be extracted as separate files.
If a file name contains non-UTF-8 characters,
it may not be archived or extracted correctly
because of a problem of the
.I pax
format specification.
.PP
The
.B sun
format extends the
.I ustar
format similar as the
.I pax
format does.
The extended headers in
.I sun
format archives are not understood
by implementations that support only the
.I pax
format and vice-versa.
The
.I sun
format has also problems with non-UTF-8 characters in file names.
.PP
The
.B GNU
.I tar
format is mostly compatible with the other
.I tar
formats,
unless an archive entry actually uses its extended features.
There are no practical limitations on files archived with this format.
The implementation of
.I cpio
is limited to expanded numerical fields
and long file names;
in particular,
there is no support for sparse files or incremental backups.
If
.I cpio
creates a multi-volume
.I GNU
archive,
it just splits a single-volume archive in multiple parts,
as with the other formats;
.I GNU
multi-volume archives are not supported.
.PP
The
.B bar
format is similar to the
.I tar
format, but can store longer file names.
It requires special implementation support to be read.
.PP
The
.B zip
format can be read in many non-Unix environments.
There are several restrictions on archives
intended for data exchange:
only regular files should be stored;
file times, permissions and ownerships
might be ignored by other implementations;
there should be no more than 65536 files in the archive;
the total archive size should not exceed 2 GB;
only
.I deflate
compression should be used.
Otherwise,
.I cpio
stores all information available with other archive formats
in extended
.I zip
file headers,
so if archive portability is of no concern,
the
.I zip
implementation in
.I cpio
can archive complete Unix file hierarchies.
.I Cpio
supports the
.I zip64
format extension for large files;
it automatically writes
.I zip64
entries if necessary.
.I Cpio
can extract all known
.I zip
format compression codes.
It does not support
.I zip
encryption.
Multi-volume
.I zip
archives are created as splitted single-volume archives,
as with the other formats written by
.IR cpio ;
generic multi-volume
.I zip
archives are not supported.
.SH EXAMPLES
Extract all files named
.I Makefile
or
.I makefile
from the archive stored on
.IR /dev/rmt/c0s0 ,
overwriting recent files:
.RS 2
.sp
cpio \-idmu \-I /dev/rmt/c0s0 \'[Mm]akefile\' \'*/[Mm]akefile\'
.RE
.PP
List the files contained in a software distribution archive:
.RS 2
.sp
cpio \-itv \-I distribution.tar.gz
.RE
.PP
Write a
.IR gzip (1)
compressed
.I ustar
archive containing all files below the directory
.I \%project
to the file
.IR \%project.tar.gz ,
excluding all directories named
.I CVS
or
.I SCCS
and their contents:
.RS 2
.sp
find project \-depth \-print | egrep \-v \'/(CVS|SCCS)(/|$)\' |
.br
      cpio \-o \-H ustar | gzip \-c > project.tar.gz
.RE
.PP
Copy the directory
.I work
and its contents
to the directory
.IR \%savedfiles :
.RS 2
.sp
find work \-depth \-print | cpio \-pdm savedfiles
.RE
.PP
Self-extracting zip archives are not automatically recognized,
but can normally be read using the
.I \-k
option, as with
.RS 2
.sp
cpio \-itvk \-H zip \-I archive.exe
.sp
.RE
.SH "ENVIRONMENT VARIABLES"
.TP
.BR LANG ", " LC_ALL
See
.IR locale (7).
.TP
.B LC_CTYPE
Selects the mapping of bytes to characters
used for matching patterns.
.TP
.B LC_TIME
Sets the month names printed with
.IR \-tv .
.TP
.B SYSV3
If this variable is set,
the
.I \-c
option has the same effect as \fI\-H odc\fR;
\fB\-H newc\fR can be used
to select SVR4 ASCII format.
The output format of
.I \-tv
is changed, as well as the text of diagnostic messages.
.SH "SEE ALSO"
find(1),
pax(1),
tar(1)
.SH DIAGNOSTICS
.I Cpio
exits with
.sp
.TS
l8fB l.
0	after successful operation;
1	on usage errors;
2	when operation was continued after minor errors;
3	on fatal error conditions.
.TE
.SH NOTES
Device and inode numbers
are used for hard link recognition
with the various cpio formats.
Since the header space cannot hold
large numbers present in current file systems,
devices and inode numbers are set on a per-archive basis.
This enables hard link recognition with all cpio formats,
but the link connection to files appended with
.I \-A
is not preserved.
.PP
If a numeric user or group id does not fit
within the size of the header field in the selected format,
files are stored with the user id (or group id, respectively)
set to 60001.
.PP
Use of the
.I \-A
option with a
.I zip
format archive may cause data loss
if the archive was not previously created by
.I cpio
itself.
.PP
.I Cpio
cannot store file names that contain newline characters;
see the
.I NOTES
section of
.IR find (1)
for more information.
.PP
If the file names passed to
.I "cpio \-o"
begin with a slash character,
absolute path names are stored in the archive
and will be extracted to these path names later
regardless of the current working directory.
This is normally not advisable,
and relative path names should be passed to
.I cpio
only.