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