contrib/libarchive/cpio/bsdcpio.1

   1 .\" Copyright (c) 2003-2007 Tim Kientzle
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd October 7, 2012
  28 .Dt CPIO 1
  29 .Os
  30 .Sh NAME
  31 .Nm cpio
  32 .Nd copy files to and from archives
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Brq Fl i
  36 .Op Ar options
  37 .Op Ar pattern ...
  38 .Op Ar < archive
  39 .Nm
  40 .Brq Fl o
  41 .Op Ar options
  42 .Ar < name-list
  43 .Op Ar > archive
  44 .Nm
  45 .Brq Fl p
  46 .Op Ar options
  47 .Ar dest-dir
  48 .Ar < name-list
  49 .Sh DESCRIPTION
  50 .Nm
  51 copies files between archives and directories.
  52 This implementation can extract from tar, pax, cpio, zip, jar, ar,
  53 and ISO 9660 cdrom images and can create tar, pax, cpio, ar,
  54 and shar archives.
  55 .Pp
  56 The first option to
  57 .Nm
  58 is a mode indicator from the following list:
  59 .Bl -tag -compact -width indent
  60 .It Fl i
  61 Input.
  62 Read an archive from standard input (unless overridden) and extract the
  63 contents to disk or (if the
  64 .Fl t
  65 option is specified)
  66 list the contents to standard output.
  67 If one or more file patterns are specified, only files matching
  68 one of the patterns will be extracted.
  69 .It Fl o
  70 Output.
  71 Read a list of filenames from standard input and produce a new archive
  72 on standard output (unless overridden) containing the specified items.
  73 .It Fl p
  74 Pass-through.
  75 Read a list of filenames from standard input and copy the files to the
  76 specified directory.
  77 .El
  78 .Pp
  79 .Sh OPTIONS
  80 Unless specifically stated otherwise, options are applicable in
  81 all operating modes.
  82 .Bl -tag -width indent
  83 .It Fl 0 , Fl Fl null
  84 Read filenames separated by NUL characters instead of newlines.
  85 This is necessary if any of the filenames being read might contain newlines.
  86 .It Fl A
  87 (o mode only)
  88 Append to the specified archive.
  89 (Not yet implemented.)
  90 .It Fl a
  91 (o and p modes)
  92 Reset access times on files after they are read.
  93 .It Fl B
  94 (o mode only)
  95 Block output to records of 5120 bytes.
  96 .It Fl C Ar size
  97 (o mode only)
  98 Block output to records of
  99 .Ar size
 100 bytes.
 101 .It Fl c
 102 (o mode only)
 103 Use the old POSIX portable character format.
 104 Equivalent to
 105 .Fl Fl format Ar odc .
 106 .It Fl d , Fl Fl make-directories
 107 (i and p modes)
 108 Create directories as necessary.
 109 .It Fl E Ar file
 110 (i mode only)
 111 Read list of file name patterns from
 112 .Ar file
 113 to list and extract.
 114 .It Fl F Ar file , Fl Fl file Ar file
 115 Read archive from or write archive to
 116 .Ar file .
 117 .It Fl f Ar pattern
 118 (i mode only)
 119 Ignore files that match
 120 .Ar pattern .
 121 .It Fl H Ar format , Fl Fl format Ar format
 122 (o mode only)
 123 Produce the output archive in the specified format.
 124 Supported formats include:
 125 .Pp
 126 .Bl -tag -width "iso9660" -compact
 127 .It Ar cpio
 128 Synonym for
 129 .Ar odc .
 130 .It Ar newc
 131 The SVR4 portable cpio format.
 132 .It Ar odc
 133 The old POSIX.1 portable octet-oriented cpio format.
 134 .It Ar pax
 135 The POSIX.1 pax format, an extension of the ustar format.
 136 .It Ar ustar
 137 The POSIX.1 tar format.
 138 .El
 139 .Pp
 140 The default format is
 141 .Ar odc .
 142 See
 143 .Xr libarchive-formats 5
 144 for more complete information about the
 145 formats currently supported by the underlying
 146 .Xr libarchive 3
 147 library.
 148 .It Fl h , Fl Fl help
 149 Print usage information.
 150 .It Fl I Ar file
 151 Read archive from
 152 .Ar file .
 153 .It Fl i , Fl Fl extract
 154 Input mode.
 155 See above for description.
 156 .It Fl Fl insecure
 157 (i and p mode only)
 158 Disable security checks during extraction or copying.
 159 This allows extraction via symbolic links, absolute paths,
 160 and path names containing
 161 .Sq ..
 162 in the name.
 163 .It Fl J , Fl Fl xz
 164 (o mode only)
 165 Compress the file with xz-compatible compression before writing it.
 166 In input mode, this option is ignored; xz compression is recognized
 167 automatically on input.
 168 .It Fl j
 169 Synonym for
 170 .Fl y .
 171 .It Fl L
 172 (o and p modes)
 173 All symbolic links will be followed.
 174 Normally, symbolic links are archived and copied as symbolic links.
 175 With this option, the target of the link will be archived or copied instead.
 176 .It Fl l , Fl Fl link
 177 (p mode only)
 178 Create links from the target directory to the original files,
 179 instead of copying.
 180 .It Fl Fl lrzip
 181 (o mode only)
 182 Compress the resulting archive with
 183 .Xr lrzip 1 .
 184 In input mode, this option is ignored.
 185 .It Fl Fl lzma
 186 (o mode only)
 187 Compress the file with lzma-compatible compression before writing it.
 188 In input mode, this option is ignored; lzma compression is recognized
 189 automatically on input.
 190 .It Fl Fl lzop
 191 (o mode only)
 192 Compress the resulting archive with
 193 .Xr lzop 1 .
 194 In input mode, this option is ignored.
 195 .It Fl m , Fl Fl preserve-modification-time
 196 (i and p modes)
 197 Set file modification time on created files to match
 198 those in the source.
 199 .It Fl n , Fl Fl numeric-uid-gid
 200 (i mode, only with
 201 .Fl t )
 202 Display numeric uid and gid.
 203 By default,
 204 .Nm
 205 displays the user and group names when they are provided in the
 206 archive, or looks up the user and group names in the system
 207 password database.
 208 .It Fl Fl no-preserve-owner
 209 (i mode only)
 210 Do not attempt to restore file ownership.
 211 This is the default when run by non-root users.
 212 .It Fl O Ar file
 213 Write archive to
 214 .Ar file .
 215 .It Fl o , Fl Fl create
 216 Output mode.
 217 See above for description.
 218 .It Fl p , Fl Fl pass-through
 219 Pass-through mode.
 220 See above for description.
 221 .It Fl Fl preserve-owner
 222 (i mode only)
 223 Restore file ownership.
 224 This is the default when run by the root user.
 225 .It Fl Fl quiet
 226 Suppress unnecessary messages.
 227 .It Fl R Oo user Oc Ns Oo : Oc Ns Oo group Oc , Fl Fl owner Oo user Oc Ns Oo : Oc Ns Oo group Oc
 228 Set the owner and/or group on files in the output.
 229 If group is specified with no user
 230 (for example,
 231 .Fl R Ar :wheel )
 232 then the group will be set but not the user.
 233 If the user is specified with a trailing colon and no group
 234 (for example,
 235 .Fl R Ar root: )
 236 then the group will be set to the user's default group.
 237 If the user is specified with no trailing colon, then
 238 the user will be set but not the group.
 239 In
 240 .Fl i
 241 and
 242 .Fl p
 243 modes, this option can only be used by the super-user.
 244 (For compatibility, a period can be used in place of the colon.)
 245 .It Fl r
 246 (All modes.)
 247 Rename files interactively.
 248 For each file, a prompt is written to
 249 .Pa /dev/tty
 250 containing the name of the file and a line is read from
 251 .Pa /dev/tty .
 252 If the line read is blank, the file is skipped.
 253 If the line contains a single period, the file is processed normally.
 254 Otherwise, the line is taken to be the new name of the file.
 255 .It Fl t , Fl Fl list
 256 (i mode only)
 257 List the contents of the archive to stdout;
 258 do not restore the contents to disk.
 259 .It Fl u , Fl Fl unconditional
 260 (i and p modes)
 261 Unconditionally overwrite existing files.
 262 Ordinarily, an older file will not overwrite a newer file on disk.
 263 .It Fl V , Fl Fl dot
 264 Print a dot to stderr for each file as it is processed.
 265 Superseded by
 266 .Fl v .
 267 .It Fl v , Fl Fl verbose
 268 Print the name of each file to stderr as it is processed.
 269 With
 270 .Fl t ,
 271 provide a detailed listing of each file.
 272 .It Fl Fl version
 273 Print the program version information and exit.
 274 .It Fl y
 275 (o mode only)
 276 Compress the archive with bzip2-compatible compression before writing it.
 277 In input mode, this option is ignored;
 278 bzip2 compression is recognized automatically on input.
 279 .It Fl Z
 280 (o mode only)
 281 Compress the archive with compress-compatible compression before writing it.
 282 In input mode, this option is ignored;
 283 compression is recognized automatically on input.
 284 .It Fl z
 285 (o mode only)
 286 Compress the archive with gzip-compatible compression before writing it.
 287 In input mode, this option is ignored;
 288 gzip compression is recognized automatically on input.
 289 .El
 290 .Sh EXIT STATUS
 291 .Ex -std
 292 .Sh ENVIRONMENT
 293 The following environment variables affect the execution of
 294 .Nm :
 295 .Bl -tag -width ".Ev BLOCKSIZE"
 296 .It Ev LANG
 297 The locale to use.
 298 See
 299 .Xr environ 7
 300 for more information.
 301 .It Ev TZ
 302 The timezone to use when displaying dates.
 303 See
 304 .Xr environ 7
 305 for more information.
 306 .El
 307 .Sh EXAMPLES
 308 The
 309 .Nm
 310 command is traditionally used to copy file hierarchies in conjunction
 311 with the
 312 .Xr find 1
 313 command.
 314 The first example here simply copies all files from
 315 .Pa src
 316 to
 317 .Pa dest :
 318 .Dl Nm find Pa src | Nm Fl pmud Pa dest
 319 .Pp
 320 By carefully selecting options to the
 321 .Xr find 1
 322 command and combining it with other standard utilities,
 323 it is possible to exercise very fine control over which files are copied.
 324 This next example copies files from
 325 .Pa src
 326 to
 327 .Pa dest
 328 that are more than 2 days old and whose names match a particular pattern:
 329 .Dl Nm find Pa src Fl mtime Ar +2 | Nm grep foo[bar] | Nm Fl pdmu Pa dest
 330 .Pp
 331 This example copies files from
 332 .Pa src
 333 to
 334 .Pa dest
 335 that are more than 2 days old and which contain the word
 336 .Do foobar Dc :
 337 .Dl Nm find Pa src Fl mtime Ar +2 | Nm xargs Nm grep -l foobar | Nm Fl pdmu Pa dest
 338 .Sh COMPATIBILITY
 339 The mode options i, o, and p and the options
 340 a, B, c, d, f, l, m, r, t, u, and v comply with SUSv2.
 341 .Pp
 342 The old POSIX.1 standard specified that only
 343 .Fl i ,
 344 .Fl o ,
 345 and
 346 .Fl p
 347 were interpreted as command-line options.
 348 Each took a single argument of a list of modifier
 349 characters.
 350 For example, the standard syntax allows
 351 .Fl imu
 352 but does not support
 353 .Fl miu
 354 or
 355 .Fl i Fl m Fl u ,
 356 since
 357 .Ar m
 358 and
 359 .Ar u
 360 are only modifiers to
 361 .Fl i ,
 362 they are not command-line options in their own right.
 363 The syntax supported by this implementation is backwards-compatible
 364 with the standard.
 365 For best compatibility, scripts should limit themselves to the
 366 standard syntax.
 367 .Sh SEE ALSO
 368 .Xr bzip2 1 ,
 369 .Xr tar 1 ,
 370 .Xr gzip 1 ,
 371 .Xr mt 1 ,
 372 .Xr pax 1 ,
 373 .Xr libarchive 3 ,
 374 .Xr cpio 5 ,
 375 .Xr libarchive-formats 5 ,
 376 .Xr tar 5
 377 .Sh STANDARDS
 378 There is no current POSIX standard for the cpio command; it appeared
 379 in
 380 .St -p1003.1-96
 381 but was dropped from
 382 .St -p1003.1-2001 .
 383 .Pp
 384 The cpio, ustar, and pax interchange file formats are defined by
 385 .St -p1003.1-2001
 386 for the pax command.
 387 .Sh HISTORY
 388 The original
 389 .Nm cpio
 390 and
 391 .Nm find
 392 utilities were written by Dick Haight
 393 while working in AT&T's Unix Support Group.
 394 They first appeared in 1977 in PWB/UNIX 1.0, the
 395 .Dq Programmer's Work Bench
 396 system developed for use within AT&T.
 397 They were first released outside of AT&T as part of System III Unix in 1981.
 398 As a result,
 399 .Nm cpio
 400 actually predates
 401 .Nm tar ,
 402 even though it was not well-known outside of AT&T until some time later.
 403 .Pp
 404 This is a complete re-implementation based on the
 405 .Xr libarchive 3
 406 library.
 407 .Sh BUGS
 408 The cpio archive format has several basic limitations:
 409 It does not store user and group names, only numbers.
 410 As a result, it cannot be reliably used to transfer
 411 files between systems with dissimilar user and group numbering.
 412 Older cpio formats limit the user and group numbers to
 413 16 or 18 bits, which is insufficient for modern systems.
 414 The cpio archive formats cannot support files over 4 gigabytes,
 415 except for the
 416 .Dq odc
 417 variant, which can support files up to 8 gigabytes.