git.gag.com Git - debian/pax/blob - cpio.1

   1 .\"     $OpenBSD: cpio.1,v 1.28 2008/06/11 07:42:50 jmc Exp $
   2 .\"
   3 .\" Copyright (c) 1997 SigmaSoft, Th. Lockert
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\"     $OpenBSD: cpio.1,v 1.28 2008/06/11 07:42:50 jmc Exp $
  27 .\"
  28 .Dd $Mdocdate: June 11 2008 $
  29 .Dt CPIO 1
  30 .Os
  31 .Sh NAME
  32 .Nm cpio
  33 .Nd copy file archives in and out
  34 .Sh SYNOPSIS
  35 .Nm cpio
  36 .Fl o
  37 .Op Fl AaBcjLvZz
  38 .Op Fl C Ar bytes
  39 .Op Fl F Ar archive
  40 .Op Fl H Ar format
  41 .Op Fl O Ar archive
  42 .Ar \*(Lt name-list
  43 .Op Ar \*(Gt archive
  44 .Nm cpio
  45 .Fl i
  46 .Op Fl 6BbcdfjmrSstuvZz
  47 .Op Fl C Ar bytes
  48 .Op Fl E Ar file
  49 .Op Fl F Ar archive
  50 .Op Fl H Ar format
  51 .Op Fl I Ar archive
  52 .Op Ar pattern ...
  53 .Op Ar \*(Lt archive
  54 .Nm cpio
  55 .Fl p
  56 .Op Fl adLlmuv
  57 .Ar destination-directory
  58 .Ar \*(Lt name-list
  59 .Sh DESCRIPTION
  60 The
  61 .Nm
  62 command copies files to and from a
  63 .Nm
  64 archive.
  65 .Pp
  66 The options are as follows:
  67 .Bl -tag -width Ds
  68 .It Fl o
  69 Create an archive.
  70 Reads the list of files to store in the
  71 archive from standard input, and writes the archive on standard
  72 output.
  73 .Bl -tag -width Ds
  74 .It Fl A
  75 Append to the specified archive.
  76 .It Fl a
  77 Reset the access times on files that have been copied to the
  78 archive.
  79 .It Fl B
  80 Set block size of output to 5120 bytes.
  81 .It Fl C Ar bytes
  82 Set the block size of output to
  83 .Ar bytes .
  84 .It Fl c
  85 Use ASCII format for
  86 .Nm
  87 header for portability.
  88 .It Fl F Ar archive
  89 Use the specified file as the input for the archive.
  90 .It Fl H Ar format
  91 Write the archive in the specified format.
  92 Recognized formats are:
  93 .Pp
  94 .Bl -tag -width sv4cpio -compact
  95 .It Ar bcpio
  96 Old binary
  97 .Nm
  98 format.
  99 .It Ar cpio
 100 Old octal character
 101 .Nm
 102 format.
 103 .It Ar sv4cpio
 104 SVR4 hex
 105 .Nm
 106 format.
 107 .It Ar tar
 108 Old tar format.
 109 .It Ar ustar
 110 POSIX ustar format.
 111 .El
 112 .It Fl j
 113 Compress archive using the bzip2 format.
 114 The bzip2 utility must be installed separately.
 115 .It Fl L
 116 Follow symbolic links.
 117 .It Fl O Ar archive
 118 Use the specified file name as the archive to write to.
 119 .It Fl v
 120 Be verbose about operations.
 121 List filenames as they are written to the archive.
 122 .It Fl Z
 123 Compress archive using
 124 .Xr compress 1
 125 format.
 126 .It Fl z
 127 Compress archive using
 128 .Xr gzip 1
 129 format.
 130 .El
 131 .It Fl i
 132 Restore files from an archive.
 133 Reads the archive file from
 134 standard input and extracts files matching the
 135 .Ar patterns
 136 that were specified on the command line.
 137 .Bl -tag -width Ds
 138 .It Fl 6
 139 Process old-style
 140 .Nm
 141 format archives.
 142 .It Fl B
 143 Set the block size of the archive being read to 5120 bytes.
 144 .It Fl b
 145 Do byte and word swapping after reading in data from the
 146 archive, for restoring archives created on systems with
 147 a different byte order.
 148 .It Fl C Ar bytes
 149 Read archive written with a block size of
 150 .Ar bytes .
 151 .It Fl c
 152 Expect the archive headers to be in ASCII format.
 153 .It Fl d
 154 Create any intermediate directories as needed during
 155 restore.
 156 .It Fl E Ar file
 157 Read list of file name patterns to extract or list from
 158 .Ar file .
 159 .It Fl F Ar archive , Fl I Ar archive
 160 Use the specified file as the input for the archive.
 161 .It Fl f
 162 Restore all files except those matching the
 163 .Ar patterns
 164 given on the command line.
 165 .It Fl H Ar format
 166 Read an archive of the specified format.
 167 Recognized formats are:
 168 .Pp
 169 .Bl -tag -width sv4cpio -compact
 170 .It Ar bcpio
 171 Old binary
 172 .Nm
 173 format.
 174 .It Ar cpio
 175 Old octal character
 176 .Nm
 177 format.
 178 .It Ar sv4cpio
 179 SVR4 hex
 180 .Nm
 181 format.
 182 .It Ar tar
 183 Old tar format.
 184 .It Ar ustar
 185 POSIX ustar format.
 186 .El
 187 .It Fl j
 188 Uncompress archive using the bzip2 format.
 189 The bzip2 utility must be installed separately.
 190 .It Fl m
 191 Restore modification times on files.
 192 .It Fl r
 193 Rename restored files interactively.
 194 .It Fl S
 195 Swap words after reading data from the archive.
 196 .It Fl s
 197 Swap bytes after reading data from the archive.
 198 .It Fl t
 199 Only list the contents of the archive, no files or
 200 directories will be created.
 201 .It Fl u
 202 Overwrite files even when the file in the archive is
 203 older than the one that will be overwritten.
 204 .It Fl v
 205 Be verbose about operations.
 206 List filenames as they are copied in from the archive.
 207 .It Fl Z
 208 Uncompress archive using
 209 .Xr compress 1
 210 format.
 211 .It Fl z
 212 Uncompress archive using
 213 .Xr gzip 1
 214 format.
 215 .El
 216 .It Fl p
 217 Copy files from one location to another in a single pass.
 218 The list of files to copy are read from standard input and
 219 written out to a directory relative to the specified
 220 .Ar directory
 221 argument.
 222 .Bl -tag -width Ds
 223 .It Fl a
 224 Reset the access times on files that have been copied.
 225 .It Fl d
 226 Create any intermediate directories as needed to write
 227 the files at the new location.
 228 .It Fl L
 229 Follow symbolic links.
 230 .It Fl l
 231 When possible, link files rather than creating an
 232 extra copy.
 233 .It Fl m
 234 Restore modification times on files.
 235 .It Fl u
 236 Overwrite files even when the original file being copied is
 237 older than the one that will be overwritten.
 238 .It Fl v
 239 Be verbose about operations.
 240 List filenames as they are copied.
 241 .El
 242 .El
 243 .Sh ENVIRONMENT
 244 .Bl -tag -width Fl
 245 .It Ev TMPDIR
 246 Path in which to store temporary files.
 247 .El
 248 .Sh ERRORS
 249 .Nm
 250 will exit with one of the following values:
 251 .Bl -tag -width 2n
 252 .It 0
 253 All files were processed successfully.
 254 .It 1
 255 An error occurred.
 256 .El
 257 .Pp
 258 Whenever
 259 .Nm
 260 cannot create a file or a link when extracting an archive or cannot
 261 find a file while writing an archive, or cannot preserve the user
 262 ID, group ID, file mode, or access and modification times when the
 263 .Fl p
 264 option is specified, a diagnostic message is written to standard
 265 error and a non-zero exit value will be returned, but processing
 266 will continue.
 267 In the case where
 268 .Nm
 269 cannot create a link to a file,
 270 .Nm
 271 will not create a second copy of the file.
 272 .Pp
 273 If the extraction of a file from an archive is prematurely terminated
 274 by a signal or error,
 275 .Nm
 276 may have only partially extracted the file the user wanted.
 277 Additionally, the file modes of extracted files and directories may
 278 have incorrect file bits, and the modification and access times may
 279 be wrong.
 280 .Pp
 281 If the creation of an archive is prematurely terminated by a signal
 282 or error,
 283 .Nm
 284 may have only partially created the archive, which may violate the
 285 specific archive format specification.
 286 .Sh SEE ALSO
 287 .Xr pax 1 ,
 288 .Xr tar 1
 289 .Sh AUTHORS
 290 Keith Muller at the University of California, San Diego.
 291 .Sh CAVEATS
 292 Different file formats have different maximum file sizes.
 293 It is recommended that a format such as cpio or ustar
 294 be used for larger files.
 295 .Pp
 296 .Bl -column "File format" "Maximum file size" -offset indent -compact
 297 .It Sy "File format" Ta Sy "Maximum file size"
 298 .It bcpio Ta 4 Gigabytes
 299 .It sv4cpio Ta 4 Gigabytes
 300 .It cpio Ta 8 Gigabytes
 301 .It tar Ta 8 Gigabytes
 302 .It ustar Ta 8 Gigabytes
 303 .El
 304 .Sh BUGS
 305 The
 306 .Fl s
 307 and
 308 .Fl S
 309 options are currently not implemented.