doc/html/bsdcpio.1.html

   1 <!-- Creator     : groff version 1.22.3 -->
   2 <!-- CreationDate: Sun Feb 19 09:11:20 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(1) BSD General Commands Manual CPIO(1)</p>
  24
  25 <p style="margin-top: 1em"><b>NAME</b></p>
  26
  27 <p style="margin-left:6%;"><b>cpio</b> &mdash; copy files
  28 to and from archives</p>
  29
  30 <p style="margin-top: 1em"><b>SYNOPSIS</b></p>
  31
  32 <p style="margin-left:13%;"><b>cpio -i</b> [<i>options</i>]
  33 [<i>pattern&nbsp;...</i>] [<i>&lt;&nbsp;archive</i>] <b><br>
  34 cpio -o</b> [<i>options</i>] <i>&lt; name-list</i>
  35 [<i>&gt;&nbsp;archive</i>] <b><br>
  36 cpio -p</b> [<i>options</i>] <i>dest-dir &lt;
  37 name-list</i></p>
  38
  39 <p style="margin-top: 1em"><b>DESCRIPTION</b></p>
  40
  41 <p style="margin-left:6%;"><b>cpio</b> copies files between
  42 archives and directories. This implementation can extract
  43 from tar, pax, cpio, zip, jar, ar, and ISO 9660 cdrom images
  44 and can create tar, pax, cpio, ar, and shar archives.</p>
  45
  46 <p style="margin-left:6%; margin-top: 1em">The first option
  47 to <b>cpio</b> is a mode indicator from the following
  48 list:</p>
  49
  50 <p><b>-i</b></p>
  51
  52 <p style="margin-left:17%; margin-top: 1em">Input. Read an
  53 archive from standard input (unless overridden) and extract
  54 the contents to disk or (if the <b>-t</b> option is
  55 specified) list the contents to standard output. If one or
  56 more file patterns are specified, only files matching one of
  57 the patterns will be extracted.</p>
  58
  59 <p><b>-o</b></p>
  60
  61 <p style="margin-left:17%; margin-top: 1em">Output. Read a
  62 list of filenames from standard input and produce a new
  63 archive on standard output (unless overridden) containing
  64 the specified items.</p>
  65
  66 <p><b>-p</b></p>
  67
  68 <p style="margin-left:17%; margin-top: 1em">Pass-through.
  69 Read a list of filenames from standard input and copy the
  70 files to the specified directory.</p>
  71
  72 <p style="margin-top: 1em"><b>OPTIONS</b></p>
  73
  74 <p style="margin-left:6%;">Unless specifically stated
  75 otherwise, options are applicable in all operating
  76 modes.</p>
  77
  78 <p style="margin-top: 1em"><b>-0</b>, <b>--null</b></p>
  79
  80 <p style="margin-left:17%;">Read filenames separated by NUL
  81 characters instead of newlines. This is necessary if any of
  82 the filenames being read might contain newlines.</p>
  83
  84 <p style="margin-top: 1em"><b>-A</b></p>
  85
  86 <p style="margin-left:17%; margin-top: 1em">(o mode only)
  87 Append to the specified archive. (Not yet implemented.)</p>
  88
  89 <p style="margin-top: 1em"><b>-a</b></p>
  90
  91 <p style="margin-left:17%; margin-top: 1em">(o and p modes)
  92 Reset access times on files after they are read.</p>
  93
  94 <p style="margin-top: 1em"><b>-B</b></p>
  95
  96 <p style="margin-left:17%; margin-top: 1em">(o mode only)
  97 Block output to records of 5120 bytes.</p>
  98
  99 <p style="margin-top: 1em"><b>-C</b> <i>size</i></p>
 100
 101 <p style="margin-left:17%;">(o mode only) Block output to
 102 records of <i>size</i> bytes.</p>
 103
 104 <p style="margin-top: 1em"><b>-c</b></p>
 105
 106 <p style="margin-left:17%; margin-top: 1em">(o mode only)
 107 Use the old POSIX portable character format. Equivalent to
 108 <b>--format</b> <i>odc</i>.</p>
 109
 110 <p style="margin-top: 1em"><b>-d</b>,
 111 <b>--make-directories</b></p>
 112
 113 <p style="margin-left:17%;">(i and p modes) Create
 114 directories as necessary.</p>
 115
 116 <p style="margin-top: 1em"><b>-E</b> <i>file</i></p>
 117
 118 <p style="margin-left:17%;">(i mode only) Read list of file
 119 name patterns from <i>file</i> to list and extract.</p>
 120
 121 <p style="margin-top: 1em"><b>-F</b> <i>file</i>,
 122 <b>--file</b> <i>file</i></p>
 123
 124 <p style="margin-left:17%;">Read archive from or write
 125 archive to <i>file</i>.</p>
 126
 127 <p style="margin-top: 1em"><b>-f</b> <i>pattern</i></p>
 128
 129 <p style="margin-left:17%;">(i mode only) Ignore files that
 130 match <i>pattern</i>.</p>
 131
 132 <p style="margin-top: 1em"><b>-H</b> <i>format</i>,
 133 <b>--format</b> <i>format</i></p>
 134
 135 <p style="margin-left:17%;">(o mode only) Produce the
 136 output archive in the specified format. Supported formats
 137 include:</p>
 138
 139 <p style="margin-top: 1em"><i>cpio</i></p>
 140
 141 <p style="margin-left:28%; margin-top: 1em">Synonym for
 142 <i>odc</i>.</p>
 143
 144 <p><i>newc</i></p>
 145
 146 <p style="margin-left:28%; margin-top: 1em">The SVR4
 147 portable cpio format.</p>
 148
 149 <p><i>odc</i></p>
 150
 151 <p style="margin-left:28%; margin-top: 1em">The old POSIX.1
 152 portable octet-oriented cpio format.</p>
 153
 154 <p><i>pax</i></p>
 155
 156 <p style="margin-left:28%; margin-top: 1em">The POSIX.1 pax
 157 format, an extension of the ustar format.</p>
 158
 159 <p><i>ustar</i></p>
 160
 161 <p style="margin-left:28%; margin-top: 1em">The POSIX.1 tar
 162 format.</p>
 163
 164 <p style="margin-left:17%; margin-top: 1em">The default
 165 format is <i>odc</i>. See libarchive-formats(5) for more
 166 complete information about the formats currently supported
 167 by the underlying libarchive(3) library.</p>
 168
 169 <p style="margin-top: 1em"><b>-h</b>, <b>--help</b></p>
 170
 171 <p style="margin-left:17%;">Print usage information.</p>
 172
 173 <p style="margin-top: 1em"><b>-I</b> <i>file</i></p>
 174
 175 <p style="margin-left:17%;">Read archive from
 176 <i>file</i>.</p>
 177
 178 <p style="margin-top: 1em"><b>-i</b>, <b>--extract</b></p>
 179
 180 <p style="margin-left:17%;">Input mode. See above for
 181 description.</p>
 182
 183 <p style="margin-top: 1em"><b>--insecure</b></p>
 184
 185 <p style="margin-left:17%;">(i and p mode only) Disable
 186 security checks during extraction or copying. This allows
 187 extraction via symbolic links, absolute paths, and path
 188 names containing &rsquo;..&rsquo; in the name.</p>
 189
 190 <p style="margin-top: 1em"><b>-J</b>, <b>--xz</b></p>
 191
 192 <p style="margin-left:17%;">(o mode only) Compress the file
 193 with xz-compatible compression before writing it. In input
 194 mode, this option is ignored; xz compression is recognized
 195 automatically on input.</p>
 196
 197 <p style="margin-top: 1em"><b>-j</b></p>
 198
 199 <p style="margin-left:17%; margin-top: 1em">Synonym for
 200 <b>-y</b>.</p>
 201
 202 <p style="margin-top: 1em"><b>-L</b></p>
 203
 204 <p style="margin-left:17%; margin-top: 1em">(o and p modes)
 205 All symbolic links will be followed. Normally, symbolic
 206 links are archived and copied as symbolic links. With this
 207 option, the target of the link will be archived or copied
 208 instead.</p>
 209
 210 <p style="margin-top: 1em"><b>-l</b>, <b>--link</b></p>
 211
 212 <p style="margin-left:17%;">(p mode only) Create links from
 213 the target directory to the original files, instead of
 214 copying.</p>
 215
 216 <p style="margin-top: 1em"><b>--lrzip</b></p>
 217
 218 <p style="margin-left:17%;">(o mode only) Compress the
 219 resulting archive with lrzip(1). In input mode, this option
 220 is ignored.</p>
 221
 222 <p style="margin-top: 1em"><b>--lz4</b></p>
 223
 224 <p style="margin-left:17%; margin-top: 1em">(o mode only)
 225 Compress the archive with lz4-compatible compression before
 226 writing it. In input mode, this option is ignored; lz4
 227 compression is recognized automatically on input.</p>
 228
 229 <p style="margin-top: 1em"><b>--lzma</b></p>
 230
 231 <p style="margin-left:17%; margin-top: 1em">(o mode only)
 232 Compress the file with lzma-compatible compression before
 233 writing it. In input mode, this option is ignored; lzma
 234 compression is recognized automatically on input.</p>
 235
 236 <p style="margin-top: 1em"><b>--lzop</b></p>
 237
 238 <p style="margin-left:17%; margin-top: 1em">(o mode only)
 239 Compress the resulting archive with lzop(1). In input mode,
 240 this option is ignored.</p>
 241
 242 <p style="margin-top: 1em"><b>--passphrase</b>
 243 <i>passphrase</i></p>
 244
 245 <p style="margin-left:17%;">The <i>passphrase</i> is used
 246 to extract or create an encrypted archive. Currently, zip is
 247 only a format that <b>cpio</b> can handle encrypted
 248 archives. You shouldn&rsquo;t use this option unless you
 249 realize how insecure use of this option is.</p>
 250
 251 <p style="margin-top: 1em"><b>-m</b>,
 252 <b>--preserve-modification-time</b></p>
 253
 254 <p style="margin-left:17%;">(i and p modes) Set file
 255 modification time on created files to match those in the
 256 source.</p>
 257
 258 <p style="margin-top: 1em"><b>-n</b>,
 259 <b>--numeric-uid-gid</b></p>
 260
 261 <p style="margin-left:17%;">(i mode, only with <b>-t</b>)
 262 Display numeric uid and gid. By default, <b>cpio</b>
 263 displays the user and group names when they are provided in
 264 the archive, or looks up the user and group names in the
 265 system password database.</p>
 266
 267 <p style="margin-top: 1em"><b>--no-preserve-owner</b></p>
 268
 269 <p style="margin-left:17%;">(i mode only) Do not attempt to
 270 restore file ownership. This is the default when run by
 271 non-root users.</p>
 272
 273 <p style="margin-top: 1em"><b>-O</b> <i>file</i></p>
 274
 275 <p style="margin-left:17%;">Write archive to
 276 <i>file</i>.</p>
 277
 278 <p style="margin-top: 1em"><b>-o</b>, <b>--create</b></p>
 279
 280 <p style="margin-left:17%;">Output mode. See above for
 281 description.</p>
 282
 283 <p style="margin-top: 1em"><b>-p</b>,
 284 <b>--pass-through</b></p>
 285
 286 <p style="margin-left:17%;">Pass-through mode. See above
 287 for description.</p>
 288
 289 <p style="margin-top: 1em"><b>--preserve-owner</b></p>
 290
 291 <p style="margin-left:17%;">(i mode only) Restore file
 292 ownership. This is the default when run by the root
 293 user.</p>
 294
 295 <p style="margin-top: 1em"><b>--quiet</b></p>
 296
 297 <p style="margin-left:17%;">Suppress unnecessary
 298 messages.</p>
 299
 300 <p style="margin-top: 1em"><b>-R</b> [ <br>
 301 user][ <br>
 302 :][ <br>
 303 group], <b>--owner</b> [ <br>
 304 user][ <br>
 305 :][ <br>
 306 group]</p>
 307
 308 <p style="margin-left:17%;">Set the owner and/or group on
 309 files in the output. If group is specified with no user (for
 310 example, <b>-R</b> <i>:wheel</i>) then the group will be set
 311 but not the user. If the user is specified with a trailing
 312 colon and no group (for example, <b>-R</b> <i>root:</i>)
 313 then the group will be set to the user&rsquo;s default
 314 group. If the user is specified with no trailing colon, then
 315 the user will be set but not the group. In <b>-i</b> and
 316 <b>-p</b> modes, this option can only be used by the
 317 super-user. (For compatibility, a period can be used in
 318 place of the colon.)</p>
 319
 320 <p style="margin-top: 1em"><b>-r</b></p>
 321
 322 <p style="margin-left:17%; margin-top: 1em">(All modes.)
 323 Rename files interactively. For each file, a prompt is
 324 written to <i>/dev/tty</i> containing the name of the file
 325 and a line is read from <i>/dev/tty</i>. If the line read is
 326 blank, the file is skipped. If the line contains a single
 327 period, the file is processed normally. Otherwise, the line
 328 is taken to be the new name of the file.</p>
 329
 330 <p style="margin-top: 1em"><b>-t</b>, <b>--list</b></p>
 331
 332 <p style="margin-left:17%;">(i mode only) List the contents
 333 of the archive to stdout; do not restore the contents to
 334 disk.</p>
 335
 336 <p style="margin-top: 1em"><b>-u</b>,
 337 <b>--unconditional</b></p>
 338
 339 <p style="margin-left:17%;">(i and p modes) Unconditionally
 340 overwrite existing files. Ordinarily, an older file will not
 341 overwrite a newer file on disk.</p>
 342
 343 <p style="margin-top: 1em"><b>-V</b>, <b>--dot</b></p>
 344
 345 <p style="margin-left:17%;">Print a dot to stderr for each
 346 file as it is processed. Superseded by <b>-v</b>.</p>
 347
 348 <p style="margin-top: 1em"><b>-v</b>, <b>--verbose</b></p>
 349
 350 <p style="margin-left:17%;">Print the name of each file to
 351 stderr as it is processed. With <b>-t</b>, provide a
 352 detailed listing of each file.</p>
 353
 354 <p style="margin-top: 1em"><b>--version</b></p>
 355
 356 <p style="margin-left:17%;">Print the program version
 357 information and exit.</p>
 358
 359 <p style="margin-top: 1em"><b>-y</b></p>
 360
 361 <p style="margin-left:17%; margin-top: 1em">(o mode only)
 362 Compress the archive with bzip2-compatible compression
 363 before writing it. In input mode, this option is ignored;
 364 bzip2 compression is recognized automatically on input.</p>
 365
 366 <p style="margin-top: 1em"><b>-Z</b></p>
 367
 368 <p style="margin-left:17%; margin-top: 1em">(o mode only)
 369 Compress the archive with compress-compatible compression
 370 before writing it. In input mode, this option is ignored;
 371 compression is recognized automatically on input.</p>
 372
 373 <p style="margin-top: 1em"><b>-z</b></p>
 374
 375 <p style="margin-left:17%; margin-top: 1em">(o mode only)
 376 Compress the archive with gzip-compatible compression before
 377 writing it. In input mode, this option is ignored; gzip
 378 compression is recognized automatically on input.</p>
 379
 380 <p style="margin-top: 1em"><b>EXIT STATUS</b></p>
 381
 382 <p style="margin-left:6%;">The <b>cpio</b> utility
 383 exits&nbsp;0 on success, and&nbsp;&gt;0 if an error
 384 occurs.</p>
 385
 386 <p style="margin-top: 1em"><b>ENVIRONMENT</b></p>
 387
 388 <p style="margin-left:6%;">The following environment
 389 variables affect the execution of <b>cpio</b>:</p>
 390
 391 <p style="margin-top: 1em">LANG</p>
 392
 393 <p style="margin-left:21%; margin-top: 1em">The locale to
 394 use. See environ(7) for more information.</p>
 395
 396 <p style="margin-top: 1em">TZ</p>
 397
 398 <p style="margin-left:21%; margin-top: 1em">The timezone to
 399 use when displaying dates. See environ(7) for more
 400 information.</p>
 401
 402 <p style="margin-top: 1em"><b>EXAMPLES</b></p>
 403
 404 <p style="margin-left:6%;">The <b>cpio</b> command is
 405 traditionally used to copy file hierarchies in conjunction
 406 with the find(1) command. The first example here simply
 407 copies all files from <i>src</i> to <i>dest</i>:</p>
 408
 409 <p style="margin-left:14%;"><b>find</b> <i>src</i> |
 410 <b>cpio -pmud</b> <i>dest</i></p>
 411
 412 <p style="margin-left:6%; margin-top: 1em">By carefully
 413 selecting options to the find(1) command and combining it
 414 with other standard utilities, it is possible to exercise
 415 very fine control over which files are copied. This next
 416 example copies files from <i>src</i> to <i>dest</i> that are
 417 more than 2 days old and whose names match a particular
 418 pattern:</p>
 419
 420 <p style="margin-left:14%;"><b>find</b> <i>src</i>
 421 <b>-mtime</b> <i>+2</i> | <b>grep foo[bar]</b> | <b>cpio
 422 -pdmu</b> <i>dest</i></p>
 423
 424 <p style="margin-left:6%; margin-top: 1em">This example
 425 copies files from <i>src</i> to <i>dest</i> that are more
 426 than 2 days old and which contain the word
 427 &rsquo;&rsquo;</p>
 428
 429 <p>foobar &rsquo;&rsquo;:</p>
 430
 431 <p style="margin-left:14%;"><b>find</b> <i>src</i>
 432 <b>-mtime</b> <i>+2</i> | <b>xargs grep -l foobar</b> |
 433 <b>cpio -pdmu</b> <i>dest</i></p>
 434
 435 <p style="margin-top: 1em"><b>COMPATIBILITY</b></p>
 436
 437 <p style="margin-left:6%;">The mode options i, o, and p and
 438 the options a, B, c, d, f, l, m, r, t, u, and v comply with
 439 SUSv2.</p>
 440
 441 <p style="margin-left:6%; margin-top: 1em">The old POSIX.1
 442 standard specified that only <b>-i</b>, <b>-o</b>, and
 443 <b>-p</b> were interpreted as command-line options. Each
 444 took a single argument of a list of modifier characters. For
 445 example, the standard syntax allows <b>-imu</b> but does not
 446 support <b>-miu</b> or <b>-i -m -u</b>, since <i>m</i> and
 447 <i>u</i> are only modifiers to <b>-i</b>, they are not
 448 command-line options in their own right. The syntax
 449 supported by this implementation is backwards-compatible
 450 with the standard. For best compatibility, scripts should
 451 limit themselves to the standard syntax.</p>
 452
 453 <p style="margin-top: 1em"><b>SEE ALSO</b></p>
 454
 455 <p style="margin-left:6%;">bzip2(1), tar(1), gzip(1),
 456 mt(1), pax(1), libarchive(3), cpio(5),
 457 libarchive-formats(5), tar(5)</p>
 458
 459 <p style="margin-top: 1em"><b>STANDARDS</b></p>
 460
 461 <p style="margin-left:6%;">There is no current POSIX
 462 standard for the cpio command; it appeared in ISO/IEC
 463 9945-1:1996 (&rsquo;&rsquo;POSIX.1&rsquo;&rsquo;) but was
 464 dropped from IEEE Std 1003.1-2001
 465 (&rsquo;&rsquo;POSIX.1&rsquo;&rsquo;).</p>
 466
 467 <p style="margin-left:6%; margin-top: 1em">The cpio, ustar,
 468 and pax interchange file formats are defined by IEEE Std
 469 1003.1-2001 (&rsquo;&rsquo;POSIX.1&rsquo;&rsquo;) for the
 470 pax command.</p>
 471
 472 <p style="margin-top: 1em"><b>HISTORY</b></p>
 473
 474 <p style="margin-left:6%;">The original <b>cpio</b> and
 475 <b>find</b> utilities were written by Dick Haight while
 476 working in AT&amp;T&rsquo;s Unix Support Group. They first
 477 appeared in 1977 in PWB/UNIX 1.0, the
 478 &rsquo;&rsquo;Programmer&rsquo;s Work Bench&rsquo;&rsquo;
 479 system developed for use within AT&amp;T. They were first
 480 released outside of AT&amp;T as part of System III Unix in
 481 1981. As a result, <b>cpio</b> actually predates <b>tar</b>,
 482 even though it was not well-known outside of AT&amp;T until
 483 some time later.</p>
 484
 485 <p style="margin-left:6%; margin-top: 1em">This is a
 486 complete re-implementation based on the libarchive(3)
 487 library.</p>
 488
 489 <p style="margin-top: 1em"><b>BUGS</b></p>
 490
 491 <p style="margin-left:6%;">The cpio archive format has
 492 several basic limitations: It does not store user and group
 493 names, only numbers. As a result, it cannot be reliably used
 494 to transfer files between systems with dissimilar user and
 495 group numbering. Older cpio formats limit the user and group
 496 numbers to 16 or 18 bits, which is insufficient for modern
 497 systems. The cpio archive formats cannot support files over
 498 4 gigabytes, except for the &rsquo;&rsquo;odc&rsquo;&rsquo;
 499 variant, which can support files up to 8 gigabytes.</p>
 500
 501 <p style="margin-left:6%; margin-top: 1em">BSD
 502 September&nbsp;16, 2014 BSD</p>
 503 <hr>
 504 </body>
 505 </html>