doc/html/cpio.5.html

   1 <!-- Creator     : groff version 1.22.3 -->
   2 <!-- CreationDate: Sat Feb 25 11:22:06 2017 -->
   3 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   4 "http://www.w3.org/TR/html4/loose.dtd">
   5 <html>
   6 <head>
   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 }
  15 </style>
  16 <title></title>
  17 </head>
  18 <body>
  19
  20 <hr>
  21
  22
  23 <p>CPIO(5) BSD File Formats Manual CPIO(5)</p>
  24
  25 <p style="margin-top: 1em"><b>NAME</b></p>
  26
  27 <p style="margin-left:6%;"><b>cpio</b> &mdash; format of
  28 cpio archive files</p>
  29
  30 <p style="margin-top: 1em"><b>DESCRIPTION</b></p>
  31
  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>
  36
  37 <p style="margin-left:6%; margin-top: 1em"><b>General
  38 Format</b> <br>
  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 &lsquo;&lsquo;TRAILER!!!&rsquo;&rsquo;.</p>
  50
  51 <p style="margin-left:6%; margin-top: 1em"><b>PWB
  52 format</b> <br>
  53 XXX Any documentation of the original PWB/UNIX 1.0 format?
  54 XXX</p>
  55
  56 <p style="margin-left:6%; margin-top: 1em"><b>Old Binary
  57 Format</b> <br>
  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>
  61
  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>
  72
  73 <table width="100%" border="0" rules="none" frame="void"
  74        cellspacing="0" cellpadding="0">
  75 <tr valign="top" align="left">
  76 <td width="24%"></td>
  77 <td width="11%">
  78
  79
  80 <p>unsigned short c_mtime[2];</p></td>
  81 <td width="65%">
  82 </td></tr>
  83 </table>
  84
  85 <p style="margin-left:14%;">unsigned short c_namesize;</p>
  86
  87 <table width="100%" border="0" rules="none" frame="void"
  88        cellspacing="0" cellpadding="0">
  89 <tr valign="top" align="left">
  90 <td width="24%"></td>
  91 <td width="76%">
  92
  93
  94 <p>unsigned short c_filesize[2];</p></td></tr>
  95 </table>
  96
  97 <p style="margin-left:14%;">};</p>
  98
  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>
 103
 104 <p style="margin-top: 1em"><i>magic</i></p>
 105
 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>
 110
 111 <p style="margin-top: 1em"><i>dev</i>, <i>ino</i></p>
 112
 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
 118 entry.</p>
 119
 120 <p style="margin-top: 1em"><i>mode</i></p>
 121
 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>
 125
 126 <p>0170000</p>
 127
 128 <p style="margin-left:28%; margin-top: 1em">This masks the
 129 file type bits.</p>
 130
 131 <p>0140000</p>
 132
 133 <p style="margin-left:28%; margin-top: 1em">File type value
 134 for sockets.</p>
 135
 136 <p>0120000</p>
 137
 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>
 141
 142 <p>0100000</p>
 143
 144 <p style="margin-left:28%; margin-top: 1em">File type value
 145 for regular files.</p>
 146
 147 <p>0060000</p>
 148
 149 <p style="margin-left:28%; margin-top: 1em">File type value
 150 for block special devices.</p>
 151
 152 <p>0040000</p>
 153
 154 <p style="margin-left:28%; margin-top: 1em">File type value
 155 for directories.</p>
 156
 157 <p>0020000</p>
 158
 159 <p style="margin-left:28%; margin-top: 1em">File type value
 160 for character special devices.</p>
 161
 162 <p>0010000</p>
 163
 164 <p style="margin-left:28%; margin-top: 1em">File type value
 165 for named pipes or FIFOs.</p>
 166
 167 <p>0004000</p>
 168
 169 <p style="margin-left:28%; margin-top: 1em">SUID bit.</p>
 170
 171 <p>0002000</p>
 172
 173 <p style="margin-left:28%; margin-top: 1em">SGID bit.</p>
 174
 175 <p>0001000</p>
 176
 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>
 180
 181 <p>0000777</p>
 182
 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>
 186
 187 <p style="margin-top: 1em"><i>uid</i>, <i>gid</i></p>
 188
 189 <p style="margin-left:17%;">The numeric user id and group
 190 id of the owner.</p>
 191
 192 <p style="margin-top: 1em"><i>nlink</i></p>
 193
 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>
 198
 199 <p style="margin-top: 1em"><i>rdev</i></p>
 200
 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>
 205
 206 <p style="margin-top: 1em"><i>mtime</i></p>
 207
 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
 214 order.</p>
 215
 216 <p style="margin-top: 1em"><i>namesize</i></p>
 217
 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>
 221
 222 <p style="margin-top: 1em"><i>filesize</i></p>
 223
 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>
 228
 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
 233 even length.</p>
 234
 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>
 238
 239 <p style="margin-left:6%; margin-top: 1em"><b>Portable
 240 ASCII Format</b> <br>
 241 Version&nbsp;2 of the Single UNIX Specification
 242 (&lsquo;&lsquo;SUSv2&rsquo;&rsquo;) standardized an ASCII
 243 variant that is portable across all platforms. It is
 244 commonly known as the &lsquo;&lsquo;old
 245 character&rsquo;&rsquo; format or as the
 246 &lsquo;&lsquo;odc&rsquo;&rsquo; 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>
 249
 250 <p style="margin-left:14%; margin-top: 1em">struct
 251 cpio_odc_header { <br>
 252 char c_magic[6]; <br>
 253 char c_dev[6]; <br>
 254 char c_ino[6]; <br>
 255 char c_mode[6]; <br>
 256 char c_uid[6]; <br>
 257 char c_gid[6]; <br>
 258 char c_nlink[6]; <br>
 259 char c_rdev[6]; <br>
 260 char c_mtime[11]; <br>
 261 char c_namesize[6]; <br>
 262 char c_filesize[11]; <br>
 263 };</p>
 264
 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
 272 field.</p>
 273
 274 <p style="margin-left:6%; margin-top: 1em"><b>New ASCII
 275 Format</b> <br>
 276 The &quot;new&quot; 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>
 279
 280 <p style="margin-left:14%; margin-top: 1em">struct
 281 cpio_newc_header { <br>
 282 char c_magic[6]; <br>
 283 char c_ino[8]; <br>
 284 char c_mode[8]; <br>
 285 char c_uid[8]; <br>
 286 char c_gid[8]; <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>
 296 };</p>
 297
 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>
 301
 302 <p style="margin-top: 1em"><i>magic</i></p>
 303
 304 <p style="margin-left:17%; margin-top: 1em">The string
 305 &lsquo;&lsquo;070701&rsquo;&rsquo;.</p>
 306
 307 <p style="margin-top: 1em"><i>check</i></p>
 308
 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>
 312
 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>
 319
 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
 323 archive.</p>
 324
 325 <p style="margin-left:6%; margin-top: 1em"><b>New CRC
 326 Format</b> <br>
 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 &lsquo;&lsquo;070702&rsquo;&rsquo; 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>
 334
 335 <p style="margin-left:6%; margin-top: 1em"><b>HP
 336 variants</b> <br>
 337 The <b>cpio</b> implementation distributed with HPUX used
 338 XXXX but stored device numbers differently XXX.</p>
 339
 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>
 345
 346 <p style="margin-left:6%; margin-top: 1em">XXX Others?
 347 XXX</p>
 348
 349 <p style="margin-top: 1em"><b>SEE ALSO</b></p>
 350
 351 <p style="margin-left:6%;">cpio(1), tar(5)</p>
 352
 353 <p style="margin-top: 1em"><b>STANDARDS</b></p>
 354
 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&nbsp;2 of the Single UNIX Specification
 358 (&lsquo;&lsquo;SUSv2&rsquo;&rsquo;). 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)
 361 utility.</p>
 362
 363 <p style="margin-top: 1em"><b>HISTORY</b></p>
 364
 365 <p style="margin-left:6%;">The original cpio utility was
 366 written by Dick Haight while working in AT&amp;T&rsquo;s
 367 Unix Support Group. It appeared in 1977 as part of PWB/UNIX
 368 1.0, the &lsquo;&lsquo;Programmer&rsquo;s Work
 369 Bench&rsquo;&rsquo; derived from Version&nbsp;6 AT&amp;T
 370 UNIX that was used internally at AT&amp;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 &lsquo;&lsquo;Ancient Unix&rsquo;&rsquo; license. The
 374 character format was adopted as part of IEEE Std 1003.1-1988
 375 (&lsquo;&lsquo;POSIX.1&rsquo;&rsquo;). XXX when did
 376 &quot;newc&quot; appear? Who invented it? When did HP come
 377 out with their variant? When did Sun introduce ACLs and
 378 extended attributes? XXX</p>
 379
 380 <p style="margin-top: 1em"><b>BUGS</b></p>
 381
 382 <p style="margin-left:6%;">The
 383 &lsquo;&lsquo;CRC&rsquo;&rsquo; format is mis-named, as it
 384 uses a simple checksum and not a cyclic redundancy
 385 check.</p>
 386
 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
 390 sizes.</p>
 391
 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
 395 sizes.</p>
 396
 397 <p style="margin-left:6%; margin-top: 1em">The new ASCII
 398 format is limited to 4 gigabyte file sizes.</p>
 399
 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
 403 numbering.</p>
 404
 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>
 410
 411 <p style="margin-left:6%; margin-top: 1em">BSD
 412 December&nbsp;23, 2011 BSD</p>
 413 <hr>
 414 </body>
 415 </html>