contrib/cpio/cpio.1

   1 .TH CPIO 1L \" -*- nroff -*-
   2 .SH NAME
   3 cpio \- copy files to and from archives
   4 .SH SYNOPSIS
   5 .B cpio
   6 {\-o|\-\-create} [\-0acvABLV] [\-C bytes] [\-H format] [\-M message]
   7 [\-O [[user@]host:]archive] [\-F [[user@]host:]archive]
   8 [\-\-file=[[user@]host:]archive] [\-\-format=format] [\-\-message=message]
   9 [\-\-null] [\-\-reset-access-time] [\-\-verbose] [\-\-dot] [\-\-append]
  10 [\-\-block-size=blocks] [\-\-dereference] [\-\-io-size=bytes] [\-\-quiet]
  11 [\-\-force\-local] [\-\-help] [\-\-version] < name-list [> archive]
  12
  13 .B cpio
  14 {\-i|\-\-extract} [\-bcdfmnrtsuvBSV] [\-C bytes] [\-E file] [\-H format]
  15 [\-M message] [\-R [user][:.][group]] [\-I [[user@]host:]archive]
  16 [\-F [[user@]host:]archive] [\-\-file=[[user@]host:]archive]
  17 [\-\-make-directories] [\-\-nonmatching] [\-\-preserve-modification-time]
  18 [\-\-numeric-uid-gid] [\-\-rename] [\-\-list] [\-\-swap-bytes] [\-\-swap] [\-\-dot]
  19 [\-\-unconditional] [\-\-verbose] [\-\-block-size=blocks] [\-\-swap-halfwords]
  20 [\-\-io-size=bytes] [\-\-pattern-file=file] [\-\-format=format]
  21 [\-\-owner=[user][:.][group]] [\-\-no-preserve-owner] [\-\-message=message]
  22 [\-\-force\-local] [\-\-no\-absolute\-filenames] [\-\-sparse] [\-\-only\-verify\-crc]
  23 [\-\-quiet] [\-\-help] [\-\-version] [pattern...] [< archive]
  24
  25 .B cpio
  26 {\-p|\-\-pass-through} [\-0adlmuvLV] [\-R [user][:.][group]]
  27 [\-\-null] [\-\-reset-access-time] [\-\-make-directories] [\-\-link] [\-\-quiet]
  28 [\-\-preserve-modification-time] [\-\-unconditional] [\-\-verbose] [\-\-dot]
  29 [\-\-dereference] [\-\-owner=[user][:.][group]] [\-\-no-preserve-owner]
  30 [\-\-sparse] [\-\-help] [\-\-version] destination-directory < name-list
  31 .SH DESCRIPTION
  32 This manual page
  33 documents the GNU version of
  34 .BR cpio .
  35 .B cpio
  36 copies files into or out of a cpio or tar archive, which is a file that
  37 contains other files plus information about them, such as their
  38 file name, owner, timestamps, and access permissions.  The archive can
  39 be another file on the disk, a magnetic tape, or a pipe.
  40 .B cpio
  41 has three operating modes.
  42 .PP
  43 In copy-out mode,
  44 .B cpio
  45 copies files into an archive.  It reads a list of filenames, one per
  46 line, on the standard input, and writes the archive onto the standard
  47 output.  A typical way to generate the list of filenames is with the
  48 .B find
  49 command; you should give
  50 .B find
  51 the \-d option to minimize problems with permissions on
  52 directories that are unwritable or not searchable.
  53 .PP
  54 In copy-in mode,
  55 .B cpio
  56 copies files out of an archive or lists the archive contents.  It
  57 reads the archive from the standard input.  Any non-option command
  58 line arguments are shell globbing patterns; only files in the archive
  59 whose names match one or more of those patterns are copied from the
  60 archive.  Unlike in the shell, an initial `.' in a filename does
  61 match a wildcard at the start of a pattern, and a `/' in a filename
  62 can match wildcards.  If no patterns are given, all files are
  63 extracted.
  64 .PP
  65 In copy-pass mode,
  66 .B cpio
  67 copies files from one directory tree to another, combining the
  68 copy-out and copy-in steps without actually using an archive.
  69 It reads the list of files to copy from the standard input; the
  70 directory into which it will copy them is given as a non-option
  71 argument.
  72 .PP
  73 .B cpio
  74 supports the following archive formats: binary, old ASCII, new
  75 ASCII, crc, HPUX binary, HPUX old ASCII, old tar, and POSIX.1 tar.
  76 The binary format
  77 is obsolete because it encodes information about the files in a way
  78 that is not portable between different machine architectures.
  79 The old ASCII format is portable between different machine architectures,
  80 but should not be used on file systems with more than 65536 i-nodes.
  81 The new ASCII format is portable between different machine architectures
  82 and can be used on any size file system, but is not supported by all
  83 versions of
  84 .BR cpio ;
  85 currently, it is only supported by GNU and Unix System V R4.
  86 The crc format is
  87 like the new ASCII format, but also contains a checksum for each file
  88 which
  89 .B cpio
  90 calculates when creating an archive
  91 and verifies when the file is extracted from the archive.
  92 The HPUX formats are provided for compatibility with HPUX's cpio which
  93 stores device files differently.
  94 .PP
  95 The tar format is provided for compatibility with
  96 the
  97 .B tar
  98 program.  It can not be used to archive files with names
  99 longer than 100 characters, and can not be used to archive "special"
 100 (block or character devices) files.
 101 The POSIX.1 tar format can not be used to archive files with names longer
 102 than 255 characters (less unless they have a "/" in just the right place).
 103 .PP
 104 By default,
 105 .B cpio
 106 creates binary format archives, for compatibility with
 107 older
 108 .B cpio
 109 programs.
 110 When extracting from archives,
 111 .B cpio
 112 automatically recognizes which kind of archive it is reading and can
 113 read archives created on machines with a different byte-order.
 114 .PP
 115 Some of the options to
 116 .B cpio
 117 apply only to certain operating modes; see the SYNOPSIS section for a
 118 list of which options are allowed in which modes.
 119 .SS OPTIONS
 120 .TP
 121 .I "\-0, \-\-null"
 122 In copy-out and copy-pass modes, read a list of filenames terminated
 123 by a null character instead of a newline, so that files whose names
 124 contain newlines can be archived.  GNU
 125 .B find
 126 is one way to produce a list of null-terminated filenames.
 127 .TP
 128 .I "\-a, \-\-reset-access-time"
 129 Reset the access times of files after reading them, so that it does
 130 not look like they have just been read.
 131 .TP
 132 .I "\-A, \-\-append"
 133 Append to an existing archive.  Only works in copy-out mode.  The
 134 archive must be a disk file specified with the
 135 .I \-O
 136 or
 137 .I "\-F (\-\-file)"
 138 option.
 139 .TP
 140 .I "\-b, \-\-swap"
 141 In copy-in mode, swap both halfwords of words and bytes of halfwords
 142 in the data.  Equivalent to
 143 .IR "\-sS" .
 144 Use this option to convert 32-bit integers between big-endian and
 145 little-endian machines.
 146 .TP
 147 .I "\-B"
 148 Set the I/O block size to 5120 bytes.  Initially the block size is 512
 149 bytes.
 150 .TP
 151 .I "\-\-block-size=BLOCK-SIZE"
 152 Set the I/O block size to BLOCK-SIZE * 512 bytes.
 153 .TP
 154 .I "\-c"
 155 Use the old portable (ASCII) archive format.
 156 .TP
 157 .I "\-C IO-SIZE, \-\-io-size=IO-SIZE"
 158 Set the I/O block size to IO-SIZE bytes.
 159 .TP
 160 .I "\-d, \-\-make-directories"
 161 Create leading directories where needed.
 162 .TP
 163 .I "\-E FILE, \-\-pattern-file=FILE"
 164 In copy-in mode, read additional patterns specifying filenames to
 165 extract or list from FILE.  The lines of FILE are treated as if they
 166 had been non-option arguments to
 167 .BR cpio .
 168 .TP
 169 .I "\-f, \-\-nonmatching"
 170 Only copy files that do not match any of the given patterns.
 171 .TP
 172 .I "\-F, \-\-file=archive"
 173 Archive filename to use instead of standard input or output.  To use a
 174 tape drive on another machine as the archive, use a filename that
 175 starts with `HOSTNAME:'.  The hostname can be preceded by a
 176 username and an `@' to access the remote tape drive as that user, if
 177 you have permission to do so (typically an entry in that user's
 178 `~/.rhosts' file).
 179 .TP
 180 .I "\-\-force-local"
 181 With
 182 .IR \-F ,
 183 .IR \-I ,
 184 or
 185 .IR \-O ,
 186 take the archive file name to be a local file even if it contains a
 187 colon, which would ordinarily indicate a remote host name.
 188 .TP
 189 .I "\-H FORMAT, \-\-format=FORMAT"
 190 Use archive format FORMAT.  The valid formats are listed below;
 191 the same names are also recognized in all-caps.  The default in
 192 copy-in mode is to automatically detect the archive format, and in
 193 copy-out mode is "bin".
 194 .RS
 195 .IP bin
 196 The obsolete binary format.
 197 .IP odc
 198 The old (POSIX.1) portable format.
 199 .IP newc
 200 The new (SVR4) portable format, which supports file systems having
 201 more than 65536 i-nodes.
 202 .IP crc
 203 The new (SVR4) portable format with a checksum added.
 204 .IP tar
 205 The old tar format.
 206 .IP ustar
 207 The POSIX.1 tar format.  Also recognizes GNU
 208 .B tar
 209 archives, which are similar but not identical.
 210 .IP hpbin
 211 The obsolete binary format used by HPUX's cpio (which stores device files
 212 differently).
 213 .IP hpodc
 214 The portable format used by HPUX's cpio (which stores device files differently).
 215 .RE
 216 .TP
 217 .I "\-i, \-\-extract"
 218 Run in copy-in mode.
 219 .TP
 220 .I "\-I archive"
 221 Archive filename to use instead of standard input.  To use a
 222 tape drive on another machine as the archive, use a filename that
 223 starts with `HOSTNAME:'.  The hostname can be preceded by a
 224 username and an `@' to access the remote tape drive as that user, if
 225 you have permission to do so (typically an entry in that user's
 226 `~/.rhosts' file).
 227 .TP
 228 .I \-k
 229 Ignored; for compatibility with other versions of
 230 .BR cpio .
 231 .TP
 232 .I "\-l, \-\-link"
 233 Link files instead of copying them, when possible (usable only with the
 234 .I \-p
 235 option).
 236 .TP
 237 .I "\-L, \-\-dereference"
 238 Dereference symbolic links (copy the files that they point to instead
 239 of copying the links).
 240 .TP
 241 .I "\-m, \-\-preserve-modification-time"
 242 Retain previous file modification times when creating files.
 243 .TP
 244 .I "\-M MESSAGE, \-\-message=MESSAGE"
 245 Print MESSAGE when the end of a volume of the backup media (such as a
 246 tape or a floppy disk) is reached, to prompt the user to insert a new
 247 volume.  If MESSAGE contains the string "%d", it is replaced by the
 248 current volume number (starting at 1).
 249 .TP
 250 .I "\-n, \-\-numeric-uid-gid"
 251 In the verbose table of contents listing, show numeric UID and GID
 252 instead of translating them into names.
 253 .TP
 254 .I " \-\-no-absolute-filenames"
 255 In copy-in mode, create all files relative to the current directory,
 256 even if they have an absolute file name in the archive.
 257 .TP
 258 .I " \-\-no-preserve-owner"
 259 In copy-in mode and copy-pass mode, do not change the ownership of the
 260 files; leave them owned by the user extracting them.  This is the
 261 default for non-root users, so that users on System V don't
 262 inadvertently give away files.
 263 .TP
 264 .I "\-o, \-\-create"
 265 Run in copy-out mode.
 266 .TP
 267 .I "\-O archive"
 268 Archive filename to use instead of standard output.  To use a tape
 269 drive on another machine as the archive, use a filename that starts
 270 with `HOSTNAME:'.  The hostname can be preceded by a username and an
 271 `@' to access the remote tape drive as that user, if you have
 272 permission to do so (typically an entry in that user's `~/.rhosts'
 273 file).
 274 .TP
 275 .I " \-\-only-verify-crc"
 276 When reading a CRC format archive in copy-in mode, only verify the
 277 CRC's of each file in the archive, don't actually extract the files.
 278 .TP
 279 .I "\-p, \-\-pass-through"
 280 Run in copy-pass mode.
 281 .TP
 282 .I "\-\-quiet"
 283 Do not print the number of blocks copied.
 284 .TP
 285 .I "\-r, \-\-rename"
 286 Interactively rename files.
 287 .TP
 288 .I "\-R [user][:.][group], \-\-owner [user][:.][group]"
 289 In copy-out and copy-pass modes, set the ownership of all files created
 290 to the specified user and/or group.  Either the user or the group, or
 291 both, must be present.  If the group is omitted but the ":" or "."
 292 separator is given, use the given user's login group.  Only the
 293 super-user can change files' ownership.
 294 .TP
 295 .I "\-\-sparse"
 296 In copy-out and copy-pass modes, write files with large blocks of zeros
 297 as sparse files.
 298 .TP
 299 .I "\-s, \-\-swap-bytes"
 300 In copy-in mode, swap the bytes of each halfword (pair of bytes) in the
 301 files.
 302 .TP
 303 .I "\-S, \-\-swap-halfwords"
 304 In copy-in mode, swap the halfwords of each word (4 bytes) in the
 305 files.
 306 .TP
 307 .I "\-t, \-\-list"
 308 Print a table of contents of the input.
 309 .TP
 310 .I "\-u, \-\-unconditional"
 311 Replace all files, without asking whether to replace existing newer
 312 files with older files.
 313 .TP
 314 .I "\-v, \-\-verbose"
 315 List the files processed, or with
 316 .IR \-t ,
 317 give an `ls \-l' style table of contents listing.  In a verbose table
 318 of contents of a ustar archive, user and group names in the archive
 319 that do not exist on the local system are replaced by the names that
 320 correspond locally to the numeric UID and GID stored in the archive.
 321 .TP
 322 .I "\-V \-\-dot"
 323 Print a "." for each file processed.
 324 .TP
 325 .I "\-\-version"
 326 Print the
 327 .B cpio
 328 program version number and exit.