User Commands cpio(1)
NAME
cpio - copy file archives in and out
SYNOPSIS
cpio -i [-bBcdfkmPrsStuvV6@/] [-C bufsize] [-E file]
[-H header] [-I [-M message] [-R id] [pattern]...
cpio -o [-aABcLPvV@/] [-C bufsize] [-H header]
[-O file [-M message]
cpio -p [-adlLmPuvV@/] [-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 pat-
terns are selected. See sh(1) and OPERANDS for more informa-
tion 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
{PRIVFILECHOWNSELF} 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 out-
put, 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
SunOS 5.11 Last change: 15 Aug 2008 1
User Commands cpio(1)
destination directory tree, based on the options described
below.
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 char-
acter 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 stan-
dard 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 invisi-
ble. Access times are not reset for linked
files when cpio -pla is specified.
SunOS 5.11 Last change: 15 Aug 2008 2
User Commands cpio(1)
-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 por-
tion 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 ASCI
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 Interac-
tive 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 posi-
tive 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.
SunOS 5.11 Last change: 15 Aug 2008 3
User Commands cpio(1)
-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 ASCI header with expanded
device numbers and an addi-
tional per-file checksum.
There are no UID or GID res-
trictions associated with
this header format.
odc ASCI header with small dev-
ice numbers. This is the
IE/P1003 Data Interchange
Standard cpio header and for-
mat. It has the widest range
of portability of any of the
header formats. It is the
official format for transfer-
ring files between POSIX-
conforming systems (see stan-
dards(5)). 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 for-
mat with option -o has the
same effect as specifying the
"ustar" format: the output
SunOS 5.11 Last change: 15 Aug 2008 4
User Commands cpio(1)
archive is in ustar format,
and must be read using -H
ustar.
ustar USTAR IE/P1003 Data Interchange
Standard tar header and for-
mat. 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
tarTAR, ustarUSTAR, 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 con-
tinue 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 cor-
rupted 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 sym-
bolic link itself. Use only with the -p
option.
SunOS 5.11 Last change: 15 Aug 2008 5
User Commands cpio(1)
-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 out-
put, existing ACLs are written along with
other attributes, except for extended attri-
butes, to the standard output. ACLs are
created as special files with a special file
type. If the option is used for input, exist-
ing ACLs are extracted along with other attri-
butes from standard input. The option recog-
nizes 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 ASCI
headers for portability.
-r Interactively renames files. If the user types
a carriage return alone, the file is skipped.
If the user types a ``.'', the original path-
name is retained. Not available with cpio -p.
SunOS 5.11 Last change: 15 Aug 2008 6
User Commands cpio(1)
-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 attri-
butes in the archive. With this flag, cpio
looks for extended attributes on the files to
be placed in the archive and add them, as reg-
ular 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
SunOS 5.11 Last change: 15 Aug 2008 7
User Commands cpio(1)
the normal file data. Extended attribute files
can only be extracted from an archive as part
of a normal file extract. Attempts to expli-
citly 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 nor-
mal 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 simi-
lar to regular expressions. The following meta-
characters are defined:
* Matches any string, including the
empty string.
? Matches any single character.
[...] Matches any one of the enclosed char-
acters. 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.
SunOS 5.11 Last change: 15 Aug 2008 8
User Commands cpio(1)
! 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(5) 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 direc-
tories below the current directory as needed (-d option),
SunOS 5.11 Last change: 15 Aug 2008 9
User Commands cpio(1)
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(5) for descriptions of the following environment
variables that affect the execution of cpio: LCOLATE,
LCTYPE, LCMESAGES, LCTIME, TZ, and NLSPATH.
TMPDIR cpio creates its temporary file in /var/tmp by
default. Otherwise, it uses the directory speci-
fied by TMPDIR.
EXIT STATUS
The following exit values are returned:
0 Successful completion.
SunOS 5.11 Last change: 15 Aug 2008 10
User Commands cpio(1)
>0 An error occurred.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcsu
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(5),
environ(5), fsattr(5), largefile(5), standards(5)
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
ASCI "-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
SunOS 5.11 Last change: 15 Aug 2008 11
User Commands cpio(1)
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 charac-
ters 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
{PRIVFILECHOWNSELF} privilege, and in particular on a
system where {POSIXCHOWNRESTRICTED} is not in effect
(effectively granting this privilege to all users where not
overridden), extracted or copied files can end up with own-
ers 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, pax , tar, or cpio), 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.
SunOS 5.11 Last change: 15 Aug 2008 12
|
