pax/cpio.1

   1 .\"     $OpenBSD: cpio.1,v 1.20 2003/11/21 20:54:02 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.20 2003/11/21 20:54:02 jmc Exp $
  27 .\"
  28 .Dd February 16, 1997
  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 aABcLvzZ
  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 "< name-list"
  43 .Op Ar "> archive"
  44 .Nm cpio
  45 .Fl i
  46 .Op Fl bBcdfmrsStuvzZ6
  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 "< archive"
  54 .Nm cpio
  55 .Fl p
  56 .Op Fl adlLmuv
  57 .Ar destination-directory
  58 .Ar "< name-list"
  59 .Sh DESCRIPTION
  60 The
  61 .Nm cpio
  62 command copies files to and from a
  63 .Nm cpio
  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 cpio
  87 header for portability.
  88 .It Fl F Ar archive
  89 Use the specified file name as the archive to write to.
  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 cpio
  98 format.
  99 .It Ar cpio
 100 Old octal character
 101 .Nm cpio
 102 format.
 103 .It Ar sv4cpio
 104 SVR4 hex
 105 .Nm cpio
 106 format.
 107 .It Ar tar
 108 Old tar format.
 109 .It Ar ustar
 110 POSIX ustar format.
 111 .El
 112 .It Fl L
 113 Follow symbolic links.
 114 .It Fl O Ar archive
 115 Use the specified file name as the archive to write to.
 116 .It Fl v
 117 Be verbose about operations.
 118 List filenames as they are written to the archive.
 119 .It Fl Z
 120 Compress archive using
 121 .Xr compress 1
 122 format.
 123 .It Fl z
 124 Compress archive using
 125 .Xr gzip 1
 126 format.
 127 .El
 128 .It Fl i
 129 Restore files from an archive.
 130 Reads the archive file from
 131 standard input and extracts files matching the
 132 .Ar patterns
 133 that were specified on the command line.
 134 .Bl -tag -width Ds
 135 .It Fl 6
 136 Process old-style
 137 .Nm cpio
 138 format archives.
 139 .It Fl B
 140 Set the block size of the archive being read to 5120 bytes.
 141 .It Fl b
 142 Do byte and word swapping after reading in data from the
 143 archive, for restoring archives created on systems with
 144 a different byte order.
 145 .It Fl C Ar bytes
 146 Read archive written with a block size of
 147 .Ar bytes .
 148 .It Fl c
 149 Expect the archive headers to be in ASCII format.
 150 .It Fl d
 151 Create any intermediate directories as needed during
 152 restore.
 153 .It Fl E Ar file
 154 Read list of file name patterns to extract or list from
 155 .Ar file .
 156 .It Fl F Ar archive
 157 Use the specified file as the input for the archive.
 158 .It Fl f
 159 Restore all files except those matching the
 160 .Ar patterns
 161 given on the command line.
 162 .It Fl H Ar format
 163 Read an archive of the specified format.
 164 Recognized formats are:
 165 .Pp
 166 .Bl -tag -width sv4cpio -compact
 167 .It Ar bcpio
 168 Old binary
 169 .Nm cpio
 170 format.
 171 .It Ar cpio
 172 Old octal character
 173 .Nm cpio
 174 format.
 175 .It Ar sv4cpio
 176 SVR4 hex
 177 .Nm cpio
 178 format.
 179 .It Ar tar
 180 Old tar format.
 181 .It Ar ustar
 182 POSIX ustar format.
 183 .El
 184 .It Fl I Ar archive
 185 Use the specified file as the input for the archive.
 186 .It Fl m
 187 Restore modification times on files.
 188 .It Fl r
 189 Rename restored files interactively.
 190 .It Fl S
 191 Swap words after reading data from the archive.
 192 .It Fl s
 193 Swap bytes after reading data from the archive.
 194 .It Fl t
 195 Only list the contents of the archive, no files or
 196 directories will be created.
 197 .It Fl u
 198 Overwrite files even when the file in the archive is
 199 older than the one that will be overwritten.
 200 .It Fl v
 201 Be verbose about operations.
 202 List filenames as they are copied in from the archive.
 203 .It Fl Z
 204 Uncompress archive using
 205 .Xr compress 1
 206 format.
 207 .It Fl z
 208 Uncompress archive using
 209 .Xr gzip 1
 210 format.
 211 .El
 212 .It Fl p
 213 Copy files from one location to another in a single pass.
 214 The list of files to copy are read from standard input and
 215 written out to a directory relative to the specified
 216 .Ar directory
 217 argument.
 218 By default, an older file will not replace a newer file with the same name.
 219 .Bl -tag -width Ds
 220 .It Fl a
 221 Reset the access times on files that have been copied.
 222 .It Fl d
 223 Create any intermediate directories as needed to write
 224 the files at the new location.
 225 .It Fl L
 226 Follow symbolic links.
 227 .It Fl l
 228 When possible, link files rather than creating an
 229 extra copy.
 230 .It Fl m
 231 Restore modification times on files.
 232 .It Fl u
 233 Overwrite files even when the original file being copied is
 234 older than the one that will be overwritten.
 235 .It Fl v
 236 Be verbose about operations.
 237 List filenames as they are copied.
 238 .El
 239 .El
 240 .Sh ENVIRONMENT
 241 .Bl -tag -width Fl
 242 .It Ev TMPDIR
 243 Path in which to store temporary files.
 244 .El
 245 .Sh ERRORS
 246 .Nm cpio
 247 will exit with one of the following values:
 248 .Bl -tag -width 2n
 249 .It 0
 250 All files were processed successfully.
 251 .It 1
 252 An error occurred.
 253 .El
 254 .Pp
 255 Whenever
 256 .Nm cpio
 257 cannot create a file or a link when extracting an archive or cannot
 258 find a file while writing an archive, or cannot preserve the user
 259 ID, group ID, file mode, or access and modification times when the
 260 .Fl p
 261 option is specified, a diagnostic message is written to standard
 262 error and a non-zero exit value will be returned, but processing
 263 will continue.
 264 In the case where
 265 .Nm cpio
 266 cannot create a link to a file,
 267 .Nm cpio
 268 will not create a second copy of the file.
 269 .Pp
 270 If the extraction of a file from an archive is prematurely terminated
 271 by a signal or error,
 272 .Nm cpio
 273 may have only partially extracted the file the user wanted.
 274 Additionally, the file modes of extracted files and directories may
 275 have incorrect file bits, and the modification and access times may
 276 be wrong.
 277 .Pp
 278 If the creation of an archive is prematurely terminated by a signal
 279 or error,
 280 .Nm cpio
 281 may have only partially created the archive, which may violate the
 282 specific archive format specification.
 283 .Sh SEE ALSO
 284 .Xr pax 1 ,
 285 .Xr tar 1
 286 .Sh AUTHORS
 287 Keith Muller at the University of California, San Diego.
 288 .Sh BUGS
 289 The
 290 .Fl s
 291 and
 292 .Fl S
 293 options are currently not implemented.