|
Packit Service |
1d0348 |
CPIO(5) BSD File Formats Manual CPIO(5)
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
NAME
|
|
Packit Service |
1d0348 |
cpio — format of cpio archive files
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
DESCRIPTION
|
|
Packit Service |
1d0348 |
The cpio archive format collects any number of files, directories, and
|
|
Packit Service |
1d0348 |
other file system objects (symbolic links, device nodes, etc.) into a
|
|
Packit Service |
1d0348 |
single stream of bytes.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
General Format
|
|
Packit Service |
1d0348 |
Each file system object in a cpio archive comprises a header record with
|
|
Packit Service |
1d0348 |
basic numeric metadata followed by the full pathname of the entry and the
|
|
Packit Service |
1d0348 |
file data. The header record stores a series of integer values that gen‐
|
|
Packit Service |
1d0348 |
erally follow the fields in struct stat. (See stat(2) for details.) The
|
|
Packit Service |
1d0348 |
variants differ primarily in how they store those integers (binary,
|
|
Packit Service |
1d0348 |
octal, or hexadecimal). The header is followed by the pathname of the
|
|
Packit Service |
1d0348 |
entry (the length of the pathname is stored in the header) and any file
|
|
Packit Service |
1d0348 |
data. The end of the archive is indicated by a special record with the
|
|
Packit Service |
1d0348 |
pathname “TRAILER!!!”.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
PWB format
|
|
Packit Service |
1d0348 |
XXX Any documentation of the original PWB/UNIX 1.0 format? XXX
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
Old Binary Format
|
|
Packit Service |
1d0348 |
The old binary cpio format stores numbers as 2-byte and 4-byte binary
|
|
Packit Service |
1d0348 |
values. Each entry begins with a header in the following format:
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
struct header_old_cpio {
|
|
Packit Service |
1d0348 |
unsigned short c_magic;
|
|
Packit Service |
1d0348 |
unsigned short c_dev;
|
|
Packit Service |
1d0348 |
unsigned short c_ino;
|
|
Packit Service |
1d0348 |
unsigned short c_mode;
|
|
Packit Service |
1d0348 |
unsigned short c_uid;
|
|
Packit Service |
1d0348 |
unsigned short c_gid;
|
|
Packit Service |
1d0348 |
unsigned short c_nlink;
|
|
Packit Service |
1d0348 |
unsigned short c_rdev;
|
|
Packit Service |
1d0348 |
unsigned short c_mtime[2];
|
|
Packit Service |
1d0348 |
unsigned short c_namesize;
|
|
Packit Service |
1d0348 |
unsigned short c_filesize[2];
|
|
Packit Service |
1d0348 |
};
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
The unsigned short fields here are 16-bit integer values; the unsigned
|
|
Packit Service |
1d0348 |
int fields are 32-bit integer values. The fields are as follows
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
magic The integer value octal 070707. This value can be used to deter‐
|
|
Packit Service |
1d0348 |
mine whether this archive is written with little-endian or big-
|
|
Packit Service |
1d0348 |
endian integers.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
dev, ino
|
|
Packit Service |
1d0348 |
The device and inode numbers from the disk. These are used by
|
|
Packit Service |
1d0348 |
programs that read cpio archives to determine when two entries
|
|
Packit Service |
1d0348 |
refer to the same file. Programs that synthesize cpio archives
|
|
Packit Service |
1d0348 |
should be careful to set these to distinct values for each entry.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
mode The mode specifies both the regular permissions and the file
|
|
Packit Service |
1d0348 |
type. It consists of several bit fields as follows:
|
|
Packit Service |
1d0348 |
0170000 This masks the file type bits.
|
|
Packit Service |
1d0348 |
0140000 File type value for sockets.
|
|
Packit Service |
1d0348 |
0120000 File type value for symbolic links. For symbolic links,
|
|
Packit Service |
1d0348 |
the link body is stored as file data.
|
|
Packit Service |
1d0348 |
0100000 File type value for regular files.
|
|
Packit Service |
1d0348 |
0060000 File type value for block special devices.
|
|
Packit Service |
1d0348 |
0040000 File type value for directories.
|
|
Packit Service |
1d0348 |
0020000 File type value for character special devices.
|
|
Packit Service |
1d0348 |
0010000 File type value for named pipes or FIFOs.
|
|
Packit Service |
1d0348 |
0004000 SUID bit.
|
|
Packit Service |
1d0348 |
0002000 SGID bit.
|
|
Packit Service |
1d0348 |
0001000 Sticky bit. On some systems, this modifies the behavior
|
|
Packit Service |
1d0348 |
of executables and/or directories.
|
|
Packit Service |
1d0348 |
0000777 The lower 9 bits specify read/write/execute permissions
|
|
Packit Service |
1d0348 |
for world, group, and user following standard POSIX con‐
|
|
Packit Service |
1d0348 |
ventions.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
uid, gid
|
|
Packit Service |
1d0348 |
The numeric user id and group id of the owner.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
nlink The number of links to this file. Directories always have a
|
|
Packit Service |
1d0348 |
value of at least two here. Note that hardlinked files include
|
|
Packit Service |
1d0348 |
file data with every copy in the archive.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
rdev For block special and character special entries, this field con‐
|
|
Packit Service |
1d0348 |
tains the associated device number. For all other entry types,
|
|
Packit Service |
1d0348 |
it should be set to zero by writers and ignored by readers.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
mtime Modification time of the file, indicated as the number of seconds
|
|
Packit Service |
1d0348 |
since the start of the epoch, 00:00:00 UTC January 1, 1970. The
|
|
Packit Service |
1d0348 |
four-byte integer is stored with the most-significant 16 bits
|
|
Packit Service |
1d0348 |
first followed by the least-significant 16 bits. Each of the two
|
|
Packit Service |
1d0348 |
16 bit values are stored in machine-native byte order.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
namesize
|
|
Packit Service |
1d0348 |
The number of bytes in the pathname that follows the header.
|
|
Packit Service |
1d0348 |
This count includes the trailing NUL byte.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
filesize
|
|
Packit Service |
1d0348 |
The size of the file. Note that this archive format is limited
|
|
Packit Service |
1d0348 |
to four gigabyte file sizes. See mtime above for a description
|
|
Packit Service |
1d0348 |
of the storage of four-byte integers.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
The pathname immediately follows the fixed header. If the namesize is
|
|
Packit Service |
1d0348 |
odd, an additional NUL byte is added after the pathname. The file data
|
|
Packit Service |
1d0348 |
is then appended, padded with NUL bytes to an even length.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
Hardlinked files are not given special treatment; the full file contents
|
|
Packit Service |
1d0348 |
are included with each copy of the file.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
Portable ASCII Format
|
|
Packit Service |
1d0348 |
Version 2 of the Single UNIX Specification (“SUSv2”) standardized an
|
|
Packit Service |
1d0348 |
ASCII variant that is portable across all platforms. It is commonly
|
|
Packit Service |
1d0348 |
known as the “old character” format or as the “odc” format. It stores
|
|
Packit Service |
1d0348 |
the same numeric fields as the old binary format, but represents them as
|
|
Packit Service |
1d0348 |
6-character or 11-character octal values.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
struct cpio_odc_header {
|
|
Packit Service |
1d0348 |
char c_magic[6];
|
|
Packit Service |
1d0348 |
char c_dev[6];
|
|
Packit Service |
1d0348 |
char c_ino[6];
|
|
Packit Service |
1d0348 |
char c_mode[6];
|
|
Packit Service |
1d0348 |
char c_uid[6];
|
|
Packit Service |
1d0348 |
char c_gid[6];
|
|
Packit Service |
1d0348 |
char c_nlink[6];
|
|
Packit Service |
1d0348 |
char c_rdev[6];
|
|
Packit Service |
1d0348 |
char c_mtime[11];
|
|
Packit Service |
1d0348 |
char c_namesize[6];
|
|
Packit Service |
1d0348 |
char c_filesize[11];
|
|
Packit Service |
1d0348 |
};
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
The fields are identical to those in the old binary format. The name and
|
|
Packit Service |
1d0348 |
file body follow the fixed header. Unlike the old binary format, there
|
|
Packit Service |
1d0348 |
is no additional padding after the pathname or file contents. If the
|
|
Packit Service |
1d0348 |
files being archived are themselves entirely ASCII, then the resulting
|
|
Packit Service |
1d0348 |
archive will be entirely ASCII, except for the NUL byte that terminates
|
|
Packit Service |
1d0348 |
the name field.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
New ASCII Format
|
|
Packit Service |
1d0348 |
The "new" ASCII format uses 8-byte hexadecimal fields for all numbers and
|
|
Packit Service |
1d0348 |
separates device numbers into separate fields for major and minor num‐
|
|
Packit Service |
1d0348 |
bers.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
struct cpio_newc_header {
|
|
Packit Service |
1d0348 |
char c_magic[6];
|
|
Packit Service |
1d0348 |
char c_ino[8];
|
|
Packit Service |
1d0348 |
char c_mode[8];
|
|
Packit Service |
1d0348 |
char c_uid[8];
|
|
Packit Service |
1d0348 |
char c_gid[8];
|
|
Packit Service |
1d0348 |
char c_nlink[8];
|
|
Packit Service |
1d0348 |
char c_mtime[8];
|
|
Packit Service |
1d0348 |
char c_filesize[8];
|
|
Packit Service |
1d0348 |
char c_devmajor[8];
|
|
Packit Service |
1d0348 |
char c_devminor[8];
|
|
Packit Service |
1d0348 |
char c_rdevmajor[8];
|
|
Packit Service |
1d0348 |
char c_rdevminor[8];
|
|
Packit Service |
1d0348 |
char c_namesize[8];
|
|
Packit Service |
1d0348 |
char c_check[8];
|
|
Packit Service |
1d0348 |
};
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
Except as specified below, the fields here match those specified for the
|
|
Packit Service |
1d0348 |
old binary format above.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
magic The string “070701”.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
check This field is always set to zero by writers and ignored by read‐
|
|
Packit Service |
1d0348 |
ers. See the next section for more details.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
The pathname is followed by NUL bytes so that the total size of the fixed
|
|
Packit Service |
1d0348 |
header plus pathname is a multiple of four. Likewise, the file data is
|
|
Packit Service |
1d0348 |
padded to a multiple of four bytes. Note that this format supports only
|
|
Packit Service |
1d0348 |
4 gigabyte files (unlike the older ASCII format, which supports 8 giga‐
|
|
Packit Service |
1d0348 |
byte files).
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
In this format, hardlinked files are handled by setting the filesize to
|
|
Packit Service |
1d0348 |
zero for each entry except the last one that appears in the archive.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
New CRC Format
|
|
Packit Service |
1d0348 |
The CRC format is identical to the new ASCII format described in the pre‐
|
|
Packit Service |
1d0348 |
vious section except that the magic field is set to “070702” and the
|
|
Packit Service |
1d0348 |
check field is set to the sum of all bytes in the file data. This sum is
|
|
Packit Service |
1d0348 |
computed treating all bytes as unsigned values and using unsigned arith‐
|
|
Packit Service |
1d0348 |
metic. Only the least-significant 32 bits of the sum are stored.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
HP variants
|
|
Packit Service |
1d0348 |
The cpio implementation distributed with HPUX used XXXX but stored device
|
|
Packit Service |
1d0348 |
numbers differently XXX.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
Other Extensions and Variants
|
|
Packit Service |
1d0348 |
Sun Solaris uses additional file types to store extended file data,
|
|
Packit Service |
1d0348 |
including ACLs and extended attributes, as special entries in cpio ar‐
|
|
Packit Service |
1d0348 |
chives.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
XXX Others? XXX
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
SEE ALSO
|
|
Packit Service |
1d0348 |
cpio(1), tar(5)
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
STANDARDS
|
|
Packit Service |
1d0348 |
The cpio utility is no longer a part of POSIX or the Single Unix Stan‐
|
|
Packit Service |
1d0348 |
dard. It last appeared in Version 2 of the Single UNIX Specification
|
|
Packit Service |
1d0348 |
(“SUSv2”). It has been supplanted in subsequent standards by pax(1).
|
|
Packit Service |
1d0348 |
The portable ASCII format is currently part of the specification for the
|
|
Packit Service |
1d0348 |
pax(1) utility.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
HISTORY
|
|
Packit Service |
1d0348 |
The original cpio utility was written by Dick Haight while working in
|
|
Packit Service |
1d0348 |
AT&T's Unix Support Group. It appeared in 1977 as part of PWB/UNIX 1.0,
|
|
Packit Service |
1d0348 |
the “Programmer's Work Bench” derived from Version 6 AT&T UNIX that was
|
|
Packit Service |
1d0348 |
used internally at AT&T. Both the old binary and old character formats
|
|
Packit Service |
1d0348 |
were in use by 1980, according to the System III source released by SCO
|
|
Packit Service |
1d0348 |
under their “Ancient Unix” license. The character format was adopted as
|
|
Packit Service |
1d0348 |
part of IEEE Std 1003.1-1988 (“POSIX.1”). XXX when did "newc" appear?
|
|
Packit Service |
1d0348 |
Who invented it? When did HP come out with their variant? When did Sun
|
|
Packit Service |
1d0348 |
introduce ACLs and extended attributes? XXX
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
BUGS
|
|
Packit Service |
1d0348 |
The “CRC” format is mis-named, as it uses a simple checksum and not a
|
|
Packit Service |
1d0348 |
cyclic redundancy check.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
The old binary format is limited to 16 bits for user id, group id,
|
|
Packit Service |
1d0348 |
device, and inode numbers. It is limited to 4 gigabyte file sizes.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
The old ASCII format is limited to 18 bits for the user id, group id,
|
|
Packit Service |
1d0348 |
device, and inode numbers. It is limited to 8 gigabyte file sizes.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
The new ASCII format is limited to 4 gigabyte file sizes.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
None of the cpio formats store user or group names, which are essential
|
|
Packit Service |
1d0348 |
when moving files between systems with dissimilar user or group number‐
|
|
Packit Service |
1d0348 |
ing.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
Especially when writing older cpio variants, it may be necessary to map
|
|
Packit Service |
1d0348 |
actual device/inode values to synthesized values that fit the available
|
|
Packit Service |
1d0348 |
fields. With very large filesystems, this may be necessary even for the
|
|
Packit Service |
1d0348 |
newer formats.
|
|
Packit Service |
1d0348 |
|
|
Packit Service |
1d0348 |
BSD December 23, 2011 BSD
|