1 <!-- Creator : groff version 1.22.3 -->
2 <!-- CreationDate: Fri Apr 29 22:04:23 2016 -->
3 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
4 "http://www.w3.org/TR/html4/loose.dtd">
7 <meta name="generator" content="groff -Thtml, see www.gnu.org">
8 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
9 <meta name="Content-Style" content="text/css">
10 <style type="text/css">
11 p { margin-top: 0; margin-bottom: 0; vertical-align: top }
12 pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
13 table { margin-top: 0; margin-bottom: 0; vertical-align: top }
14 h1 { text-align: center }
23 <p>CPIO(5) BSD File Formats Manual CPIO(5)</p>
25 <p style="margin-top: 1em"><b>NAME</b></p>
27 <p style="margin-left:6%;"><b>cpio</b> — format of
28 cpio archive files</p>
30 <p style="margin-top: 1em"><b>DESCRIPTION</b></p>
32 <p style="margin-left:6%;">The <b>cpio</b> archive format
33 collects any number of files, directories, and other file
34 system objects (symbolic links, device nodes, etc.) into a
35 single stream of bytes.</p>
37 <p style="margin-left:6%; margin-top: 1em"><b>General
39 Each file system object in a <b>cpio</b> archive comprises a
40 header record with basic numeric metadata followed by the
41 full pathname of the entry and the file data. The header
42 record stores a series of integer values that generally
43 follow the fields in <i>struct stat</i>. (See stat(2) for
44 details.) The variants differ primarily in how they store
45 those integers (binary, octal, or hexadecimal). The header
46 is followed by the pathname of the entry (the length of the
47 pathname is stored in the header) and any file data. The end
48 of the archive is indicated by a special record with the
49 pathname ’’TRAILER!!!’’.</p>
51 <p style="margin-left:6%; margin-top: 1em"><b>PWB
53 XXX Any documentation of the original PWB/UNIX 1.0 format?
56 <p style="margin-left:6%; margin-top: 1em"><b>Old Binary
58 The old binary <b>cpio</b> format stores numbers as 2-byte
59 and 4-byte binary values. Each entry begins with a header in
60 the following format:</p>
62 <p style="margin-left:14%; margin-top: 1em">struct
63 header_old_cpio { <br>
64 unsigned short c_magic; <br>
65 unsigned short c_dev; <br>
66 unsigned short c_ino; <br>
67 unsigned short c_mode; <br>
68 unsigned short c_uid; <br>
69 unsigned short c_gid; <br>
70 unsigned short c_nlink; <br>
71 unsigned short c_rdev;</p>
73 <table width="100%" border="0" rules="none" frame="void"
74 cellspacing="0" cellpadding="0">
75 <tr valign="top" align="left">
80 <p>unsigned short c_mtime[2];</p></td>
85 <p style="margin-left:14%;">unsigned short c_namesize;</p>
87 <table width="100%" border="0" rules="none" frame="void"
88 cellspacing="0" cellpadding="0">
89 <tr valign="top" align="left">
94 <p>unsigned short c_filesize[2];</p></td></tr>
97 <p style="margin-left:14%;">};</p>
99 <p style="margin-left:6%; margin-top: 1em">The <i>unsigned
100 short</i> fields here are 16-bit integer values; the
101 <i>unsigned int</i> fields are 32-bit integer values. The
102 fields are as follows</p>
104 <p style="margin-top: 1em"><i>magic</i></p>
106 <p style="margin-left:17%; margin-top: 1em">The integer
107 value octal 070707. This value can be used to determine
108 whether this archive is written with little-endian or
109 big-endian integers.</p>
111 <p style="margin-top: 1em"><i>dev</i>, <i>ino</i></p>
113 <p style="margin-left:17%;">The device and inode numbers
114 from the disk. These are used by programs that read
115 <b>cpio</b> archives to determine when two entries refer to
116 the same file. Programs that synthesize <b>cpio</b> archives
117 should be careful to set these to distinct values for each
120 <p style="margin-top: 1em"><i>mode</i></p>
122 <p style="margin-left:17%; margin-top: 1em">The mode
123 specifies both the regular permissions and the file type. It
124 consists of several bit fields as follows:</p>
128 <p style="margin-left:28%; margin-top: 1em">This masks the
133 <p style="margin-left:28%; margin-top: 1em">File type value
138 <p style="margin-left:28%; margin-top: 1em">File type value
139 for symbolic links. For symbolic links, the link body is
140 stored as file data.</p>
144 <p style="margin-left:28%; margin-top: 1em">File type value
145 for regular files.</p>
149 <p style="margin-left:28%; margin-top: 1em">File type value
150 for block special devices.</p>
154 <p style="margin-left:28%; margin-top: 1em">File type value
159 <p style="margin-left:28%; margin-top: 1em">File type value
160 for character special devices.</p>
164 <p style="margin-left:28%; margin-top: 1em">File type value
165 for named pipes or FIFOs.</p>
169 <p style="margin-left:28%; margin-top: 1em">SUID bit.</p>
173 <p style="margin-left:28%; margin-top: 1em">SGID bit.</p>
177 <p style="margin-left:28%; margin-top: 1em">Sticky bit. On
178 some systems, this modifies the behavior of executables
179 and/or directories.</p>
183 <p style="margin-left:28%; margin-top: 1em">The lower 9
184 bits specify read/write/execute permissions for world,
185 group, and user following standard POSIX conventions.</p>
187 <p style="margin-top: 1em"><i>uid</i>, <i>gid</i></p>
189 <p style="margin-left:17%;">The numeric user id and group
192 <p style="margin-top: 1em"><i>nlink</i></p>
194 <p style="margin-left:17%; margin-top: 1em">The number of
195 links to this file. Directories always have a value of at
196 least two here. Note that hardlinked files include file data
197 with every copy in the archive.</p>
199 <p style="margin-top: 1em"><i>rdev</i></p>
201 <p style="margin-left:17%; margin-top: 1em">For block
202 special and character special entries, this field contains
203 the associated device number. For all other entry types, it
204 should be set to zero by writers and ignored by readers.</p>
206 <p style="margin-top: 1em"><i>mtime</i></p>
208 <p style="margin-left:17%; margin-top: 1em">Modification
209 time of the file, indicated as the number of seconds since
210 the start of the epoch, 00:00:00 UTC January 1, 1970. The
211 four-byte integer is stored with the most-significant 16
212 bits first followed by the least-significant 16 bits. Each
213 of the two 16 bit values are stored in machine-native byte
216 <p style="margin-top: 1em"><i>namesize</i></p>
218 <p style="margin-left:17%;">The number of bytes in the
219 pathname that follows the header. This count includes the
220 trailing NUL byte.</p>
222 <p style="margin-top: 1em"><i>filesize</i></p>
224 <p style="margin-left:17%;">The size of the file. Note that
225 this archive format is limited to four gigabyte file sizes.
226 See <i>mtime</i> above for a description of the storage of
227 four-byte integers.</p>
229 <p style="margin-left:6%; margin-top: 1em">The pathname
230 immediately follows the fixed header. If the <b>namesize</b>
231 is odd, an additional NUL byte is added after the pathname.
232 The file data is then appended, padded with NUL bytes to an
235 <p style="margin-left:6%; margin-top: 1em">Hardlinked files
236 are not given special treatment; the full file contents are
237 included with each copy of the file.</p>
239 <p style="margin-left:6%; margin-top: 1em"><b>Portable
240 ASCII Format</b> <br>
241 Version 2 of the Single UNIX Specification
242 (’’SUSv2’’) standardized an ASCII
243 variant that is portable across all platforms. It is
244 commonly known as the ’’old
245 character’’ format or as the
246 ’’odc’’ format. It stores the same
247 numeric fields as the old binary format, but represents them
248 as 6-character or 11-character octal values.</p>
250 <p style="margin-left:14%; margin-top: 1em">struct
251 cpio_odc_header { <br>
252 char c_magic[6]; <br>
258 char c_nlink[6]; <br>
260 char c_mtime[11]; <br>
261 char c_namesize[6]; <br>
262 char c_filesize[11]; <br>
265 <p style="margin-left:6%; margin-top: 1em">The fields are
266 identical to those in the old binary format. The name and
267 file body follow the fixed header. Unlike the old binary
268 format, there is no additional padding after the pathname or
269 file contents. If the files being archived are themselves
270 entirely ASCII, then the resulting archive will be entirely
271 ASCII, except for the NUL byte that terminates the name
274 <p style="margin-left:6%; margin-top: 1em"><b>New ASCII
276 The "new" ASCII format uses 8-byte hexadecimal
277 fields for all numbers and separates device numbers into
278 separate fields for major and minor numbers.</p>
280 <p style="margin-left:14%; margin-top: 1em">struct
281 cpio_newc_header { <br>
282 char c_magic[6]; <br>
287 char c_nlink[8]; <br>
288 char c_mtime[8]; <br>
289 char c_filesize[8]; <br>
290 char c_devmajor[8]; <br>
291 char c_devminor[8]; <br>
292 char c_rdevmajor[8]; <br>
293 char c_rdevminor[8]; <br>
294 char c_namesize[8]; <br>
295 char c_check[8]; <br>
298 <p style="margin-left:6%; margin-top: 1em">Except as
299 specified below, the fields here match those specified for
300 the old binary format above.</p>
302 <p style="margin-top: 1em"><i>magic</i></p>
304 <p style="margin-left:17%; margin-top: 1em">The string
305 ’’070701’’.</p>
307 <p style="margin-top: 1em"><i>check</i></p>
309 <p style="margin-left:17%; margin-top: 1em">This field is
310 always set to zero by writers and ignored by readers. See
311 the next section for more details.</p>
313 <p style="margin-left:6%; margin-top: 1em">The pathname is
314 followed by NUL bytes so that the total size of the fixed
315 header plus pathname is a multiple of four. Likewise, the
316 file data is padded to a multiple of four bytes. Note that
317 this format supports only 4 gigabyte files (unlike the older
318 ASCII format, which supports 8 gigabyte files).</p>
320 <p style="margin-left:6%; margin-top: 1em">In this format,
321 hardlinked files are handled by setting the filesize to zero
322 for each entry except the last one that appears in the
325 <p style="margin-left:6%; margin-top: 1em"><b>New CRC
327 The CRC format is identical to the new ASCII format
328 described in the previous section except that the magic
329 field is set to ’’070702’’ and the
330 <i>check</i> field is set to the sum of all bytes in the
331 file data. This sum is computed treating all bytes as
332 unsigned values and using unsigned arithmetic. Only the
333 least-significant 32 bits of the sum are stored.</p>
335 <p style="margin-left:6%; margin-top: 1em"><b>HP
337 The <b>cpio</b> implementation distributed with HPUX used
338 XXXX but stored device numbers differently XXX.</p>
340 <p style="margin-left:6%; margin-top: 1em"><b>Other
341 Extensions and Variants</b> <br>
342 Sun Solaris uses additional file types to store extended
343 file data, including ACLs and extended attributes, as
344 special entries in cpio archives.</p>
346 <p style="margin-left:6%; margin-top: 1em">XXX Others?
349 <p style="margin-top: 1em"><b>SEE ALSO</b></p>
351 <p style="margin-left:6%;">cpio(1), tar(5)</p>
353 <p style="margin-top: 1em"><b>STANDARDS</b></p>
355 <p style="margin-left:6%;">The <b>cpio</b> utility is no
356 longer a part of POSIX or the Single Unix Standard. It last
357 appeared in Version 2 of the Single UNIX Specification
358 (’’SUSv2’’). It has been supplanted
359 in subsequent standards by pax(1). The portable ASCII format
360 is currently part of the specification for the pax(1)
363 <p style="margin-top: 1em"><b>HISTORY</b></p>
365 <p style="margin-left:6%;">The original cpio utility was
366 written by Dick Haight while working in AT&T’s
367 Unix Support Group. It appeared in 1977 as part of PWB/UNIX
368 1.0, the ’’Programmer’s Work
369 Bench’’ derived from Version 6 AT&T
370 UNIX that was used internally at AT&T. Both the old
371 binary and old character formats were in use by 1980,
372 according to the System III source released by SCO under
373 their ’’Ancient Unix’’ license. The
374 character format was adopted as part of IEEE Std 1003.1-1988
375 (’’POSIX.1’’). XXX when did
376 "newc" appear? Who invented it? When did HP come
377 out with their variant? When did Sun introduce ACLs and
378 extended attributes? XXX</p>
380 <p style="margin-top: 1em"><b>BUGS</b></p>
382 <p style="margin-left:6%;">The
383 ’’CRC’’ format is mis-named, as it
384 uses a simple checksum and not a cyclic redundancy
387 <p style="margin-left:6%; margin-top: 1em">The old binary
388 format is limited to 16 bits for user id, group id, device,
389 and inode numbers. It is limited to 4 gigabyte file
392 <p style="margin-left:6%; margin-top: 1em">The old ASCII
393 format is limited to 18 bits for the user id, group id,
394 device, and inode numbers. It is limited to 8 gigabyte file
397 <p style="margin-left:6%; margin-top: 1em">The new ASCII
398 format is limited to 4 gigabyte file sizes.</p>
400 <p style="margin-left:6%; margin-top: 1em">None of the cpio
401 formats store user or group names, which are essential when
402 moving files between systems with dissimilar user or group
405 <p style="margin-left:6%; margin-top: 1em">Especially when
406 writing older cpio variants, it may be necessary to map
407 actual device/inode values to synthesized values that fit
408 the available fields. With very large filesystems, this may
409 be necessary even for the newer formats.</p>
411 <p style="margin-left:6%; margin-top: 1em">BSD
412 December 23, 2011 BSD</p>