doc/html/bsdcpio.1.html

   1 <!-- Creator     : groff version 1.22.3 -->
   2 <!-- CreationDate: Tue Feb 11 22:58:47 2020 -->
   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>--zstd</b></p>
 230
 231 <p style="margin-left:17%; margin-top: 1em">(o mode only)
 232 Compress the archive with zstd-compatible compression before
 233 writing it. In input mode, this option is ignored; zstd
 234 compression is recognized automatically on input.</p>
 235
 236 <p style="margin-top: 1em"><b>--lzma</b></p>
 237
 238 <p style="margin-left:17%; margin-top: 1em">(o mode only)
 239 Compress the file with lzma-compatible compression before
 240 writing it. In input mode, this option is ignored; lzma
 241 compression is recognized automatically on input.</p>
 242
 243 <p style="margin-top: 1em"><b>--lzop</b></p>
 244
 245 <p style="margin-left:17%; margin-top: 1em">(o mode only)
 246 Compress the resulting archive with lzop(1). In input mode,
 247 this option is ignored.</p>
 248
 249 <p style="margin-top: 1em"><b>--passphrase</b>
 250 <i>passphrase</i></p>
 251
 252 <p style="margin-left:17%;">The <i>passphrase</i> is used
 253 to extract or create an encrypted archive. Currently, zip is
 254 only a format that <b>cpio</b> can handle encrypted
 255 archives. You shouldn&rsquo;t use this option unless you
 256 realize how insecure use of this option is.</p>
 257
 258 <p style="margin-top: 1em"><b>-m</b>,
 259 <b>--preserve-modification-time</b></p>
 260
 261 <p style="margin-left:17%;">(i and p modes) Set file
 262 modification time on created files to match those in the
 263 source.</p>
 264
 265 <p style="margin-top: 1em"><b>-n</b>,
 266 <b>--numeric-uid-gid</b></p>
 267
 268 <p style="margin-left:17%;">(i mode, only with <b>-t</b>)
 269 Display numeric uid and gid. By default, <b>cpio</b>
 270 displays the user and group names when they are provided in
 271 the archive, or looks up the user and group names in the
 272 system password database.</p>
 273
 274 <p style="margin-top: 1em"><b>--no-preserve-owner</b></p>
 275
 276 <p style="margin-left:17%;">(i mode only) Do not attempt to
 277 restore file ownership. This is the default when run by
 278 non-root users.</p>
 279
 280 <p style="margin-top: 1em"><b>-O</b> <i>file</i></p>
 281
 282 <p style="margin-left:17%;">Write archive to
 283 <i>file</i>.</p>
 284
 285 <p style="margin-top: 1em"><b>-o</b>, <b>--create</b></p>
 286
 287 <p style="margin-left:17%;">Output mode. See above for
 288 description.</p>
 289
 290 <p style="margin-top: 1em"><b>-p</b>,
 291 <b>--pass-through</b></p>
 292
 293 <p style="margin-left:17%;">Pass-through mode. See above
 294 for description.</p>
 295
 296 <p style="margin-top: 1em"><b>--preserve-owner</b></p>
 297
 298 <p style="margin-left:17%;">(i mode only) Restore file
 299 ownership. This is the default when run by the root
 300 user.</p>
 301
 302 <p style="margin-top: 1em"><b>--quiet</b></p>
 303
 304 <p style="margin-left:17%;">Suppress unnecessary
 305 messages.</p>
 306
 307 <p style="margin-top: 1em"><b>-R</b> [ <br>
 308 user][ <br>
 309 :][ <br>
 310 group], <b>--owner</b> [ <br>
 311 user][ <br>
 312 :][ <br>
 313 group]</p>
 314
 315 <p style="margin-left:17%;">Set the owner and/or group on
 316 files in the output. If group is specified with no user (for
 317 example, <b>-R</b> <i>:wheel</i>) then the group will be set
 318 but not the user. If the user is specified with a trailing
 319 colon and no group (for example, <b>-R</b> <i>root:</i>)
 320 then the group will be set to the user&rsquo;s default
 321 group. If the user is specified with no trailing colon, then
 322 the user will be set but not the group. In <b>-i</b> and
 323 <b>-p</b> modes, this option can only be used by the
 324 super-user. (For compatibility, a period can be used in
 325 place of the colon.)</p>
 326
 327 <p style="margin-top: 1em"><b>-r</b></p>
 328
 329 <p style="margin-left:17%; margin-top: 1em">(All modes.)
 330 Rename files interactively. For each file, a prompt is
 331 written to <i>/dev/tty</i> containing the name of the file
 332 and a line is read from <i>/dev/tty</i>. If the line read is
 333 blank, the file is skipped. If the line contains a single
 334 period, the file is processed normally. Otherwise, the line
 335 is taken to be the new name of the file.</p>
 336
 337 <p style="margin-top: 1em"><b>-t</b>, <b>--list</b></p>
 338
 339 <p style="margin-left:17%;">(i mode only) List the contents
 340 of the archive to stdout; do not restore the contents to
 341 disk.</p>
 342
 343 <p style="margin-top: 1em"><b>-u</b>,
 344 <b>--unconditional</b></p>
 345
 346 <p style="margin-left:17%;">(i and p modes) Unconditionally
 347 overwrite existing files. Ordinarily, an older file will not
 348 overwrite a newer file on disk.</p>
 349
 350 <p style="margin-top: 1em"><b>-V</b>, <b>--dot</b></p>
 351
 352 <p style="margin-left:17%;">Print a dot to stderr for each
 353 file as it is processed. Superseded by <b>-v</b>.</p>
 354
 355 <p style="margin-top: 1em"><b>-v</b>, <b>--verbose</b></p>
 356
 357 <p style="margin-left:17%;">Print the name of each file to
 358 stderr as it is processed. With <b>-t</b>, provide a
 359 detailed listing of each file.</p>
 360
 361 <p style="margin-top: 1em"><b>--version</b></p>
 362
 363 <p style="margin-left:17%;">Print the program version
 364 information and exit.</p>
 365
 366 <p style="margin-top: 1em"><b>-y</b></p>
 367
 368 <p style="margin-left:17%; margin-top: 1em">(o mode only)
 369 Compress the archive with bzip2-compatible compression
 370 before writing it. In input mode, this option is ignored;
 371 bzip2 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 compress-compatible compression
 377 before writing it. In input mode, this option is ignored;
 378 compression is recognized automatically on input.</p>
 379
 380 <p style="margin-top: 1em"><b>-z</b></p>
 381
 382 <p style="margin-left:17%; margin-top: 1em">(o mode only)
 383 Compress the archive with gzip-compatible compression before
 384 writing it. In input mode, this option is ignored; gzip
 385 compression is recognized automatically on input.</p>
 386
 387 <p style="margin-top: 1em"><b>EXIT STATUS</b></p>
 388
 389 <p style="margin-left:6%;">The <b>cpio</b> utility
 390 exits&nbsp;0 on success, and&nbsp;&gt;0 if an error
 391 occurs.</p>
 392
 393 <p style="margin-top: 1em"><b>ENVIRONMENT</b></p>
 394
 395 <p style="margin-left:6%;">The following environment
 396 variables affect the execution of <b>cpio</b>:</p>
 397
 398 <p style="margin-top: 1em">LANG</p>
 399
 400 <p style="margin-left:21%; margin-top: 1em">The locale to
 401 use. See environ(7) for more information.</p>
 402
 403 <p style="margin-top: 1em">TZ</p>
 404
 405 <p style="margin-left:21%; margin-top: 1em">The timezone to
 406 use when displaying dates. See environ(7) for more
 407 information.</p>
 408
 409 <p style="margin-top: 1em"><b>EXAMPLES</b></p>
 410
 411 <p style="margin-left:6%;">The <b>cpio</b> command is
 412 traditionally used to copy file hierarchies in conjunction
 413 with the find(1) command. The first example here simply
 414 copies all files from <i>src</i> to <i>dest</i>:</p>
 415
 416 <p style="margin-left:14%;"><b>find</b> <i>src</i> |
 417 <b>cpio -pmud</b> <i>dest</i></p>
 418
 419 <p style="margin-left:6%; margin-top: 1em">By carefully
 420 selecting options to the find(1) command and combining it
 421 with other standard utilities, it is possible to exercise
 422 very fine control over which files are copied. This next
 423 example copies files from <i>src</i> to <i>dest</i> that are
 424 more than 2 days old and whose names match a particular
 425 pattern:</p>
 426
 427 <p style="margin-left:14%;"><b>find</b> <i>src</i>
 428 <b>-mtime</b> <i>+2</i> | <b>grep foo[bar]</b> | <b>cpio
 429 -pdmu</b> <i>dest</i></p>
 430
 431 <p style="margin-left:6%; margin-top: 1em">This example
 432 copies files from <i>src</i> to <i>dest</i> that are more
 433 than 2 days old and which contain the word
 434 &rsquo;&rsquo;</p>
 435
 436 <p>foobar &rsquo;&rsquo;:</p>
 437
 438 <p style="margin-left:14%;"><b>find</b> <i>src</i>
 439 <b>-mtime</b> <i>+2</i> | <b>xargs grep -l foobar</b> |
 440 <b>cpio -pdmu</b> <i>dest</i></p>
 441
 442 <p style="margin-top: 1em"><b>COMPATIBILITY</b></p>
 443
 444 <p style="margin-left:6%;">The mode options i, o, and p and
 445 the options a, B, c, d, f, l, m, r, t, u, and v comply with
 446 SUSv2.</p>
 447
 448 <p style="margin-left:6%; margin-top: 1em">The old POSIX.1
 449 standard specified that only <b>-i</b>, <b>-o</b>, and
 450 <b>-p</b> were interpreted as command-line options. Each
 451 took a single argument of a list of modifier characters. For
 452 example, the standard syntax allows <b>-imu</b> but does not
 453 support <b>-miu</b> or <b>-i -m -u</b>, since <i>m</i> and
 454 <i>u</i> are only modifiers to <b>-i</b>, they are not
 455 command-line options in their own right. The syntax
 456 supported by this implementation is backwards-compatible
 457 with the standard. For best compatibility, scripts should
 458 limit themselves to the standard syntax.</p>
 459
 460 <p style="margin-top: 1em"><b>SEE ALSO</b></p>
 461
 462 <p style="margin-left:6%;">bzip2(1), gzip(1), mt(1),
 463 pax(1), tar(1), libarchive(3), cpio(5),
 464 libarchive-formats(5), tar(5)</p>
 465
 466 <p style="margin-top: 1em"><b>STANDARDS</b></p>
 467
 468 <p style="margin-left:6%;">There is no current POSIX
 469 standard for the cpio command; it appeared in ISO/IEC
 470 9945-1:1996 (&rsquo;&rsquo;POSIX.1&rsquo;&rsquo;) but was
 471 dropped from IEEE Std 1003.1-2001
 472 (&rsquo;&rsquo;POSIX.1&rsquo;&rsquo;).</p>
 473
 474 <p style="margin-left:6%; margin-top: 1em">The cpio, ustar,
 475 and pax interchange file formats are defined by IEEE Std
 476 1003.1-2001 (&rsquo;&rsquo;POSIX.1&rsquo;&rsquo;) for the
 477 pax command.</p>
 478
 479 <p style="margin-top: 1em"><b>HISTORY</b></p>
 480
 481 <p style="margin-left:6%;">The original <b>cpio</b> and
 482 <b>find</b> utilities were written by Dick Haight while
 483 working in AT&amp;T&rsquo;s Unix Support Group. They first
 484 appeared in 1977 in PWB/UNIX 1.0, the
 485 &rsquo;&rsquo;Programmer&rsquo;s Work Bench&rsquo;&rsquo;
 486 system developed for use within AT&amp;T. They were first
 487 released outside of AT&amp;T as part of System III Unix in
 488 1981. As a result, <b>cpio</b> actually predates <b>tar</b>,
 489 even though it was not well-known outside of AT&amp;T until
 490 some time later.</p>
 491
 492 <p style="margin-left:6%; margin-top: 1em">This is a
 493 complete re-implementation based on the libarchive(3)
 494 library.</p>
 495
 496 <p style="margin-top: 1em"><b>BUGS</b></p>
 497
 498 <p style="margin-left:6%;">The cpio archive format has
 499 several basic limitations: It does not store user and group
 500 names, only numbers. As a result, it cannot be reliably used
 501 to transfer files between systems with dissimilar user and
 502 group numbering. Older cpio formats limit the user and group
 503 numbers to 16 or 18 bits, which is insufficient for modern
 504 systems. The cpio archive formats cannot support files over
 505 4 gigabytes, except for the &rsquo;&rsquo;odc&rsquo;&rsquo;
 506 variant, which can support files up to 8 gigabytes.</p>
 507
 508 <p style="margin-left:6%; margin-top: 1em">BSD
 509 September&nbsp;16, 2014 BSD</p>
 510 <hr>
 511 </body>
 512 </html>