bin/pax/cpio.1

   1 .\" $NetBSD: cpio.1,v 1.14 2015/12/19 18:48:33 wiz 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.14 2000/11/10 17:52:02 aaron Exp
  27 .\"
  28 .Dd June 18, 2011
  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 "\*[Lt] name-list"
  43 .Op Ar "\*[Gt] archive"
  44 .Nm cpio
  45 .Fl i
  46 .Op Fl 6BbcdfmrSstuvZz
  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 If the archive is of the form:
  66 .Ar [[user@]host:]file
  67 then the archive will be processed using
  68 .Xr rmt 8 .
  69 .Pp
  70 The options are as follows:
  71 .Bl -tag -width Ds
  72 .It Fl o , Fl Fl create
  73 Create an archive.
  74 Reads the list of files to store in the
  75 archive from standard input, and writes the archive on standard
  76 output.
  77 .Bl -tag -width Ds
  78 .It Fl a , Fl Fl reset-access-time
  79 Reset the access times on files that have been copied to the
  80 archive.
  81 .It Fl A , Fl Fl append
  82 Append to the specified archive.
  83 .It Fl B
  84 Set block size of output to 5120 bytes.
  85 .It Fl c
  86 Use ASCII format for
  87 .Nm
  88 header for portability.
  89 .It Fl C Ar bytes
  90 Set the block size of output to
  91 .Ar bytes .
  92 .It Fl F Ar archive
  93 .It Fl O Ar archive
  94 Use the specified file name as the archive to write to.
  95 .It Fl H Ar format
  96 Write the archive in the specified format.
  97 Recognized formats are:
  98 .Pp
  99 .Bl -tag -width sv4cpio -compact
 100 .It Ar bcpio
 101 Old binary
 102 .Nm
 103 format.
 104 .It Ar cpio
 105 Old octal character
 106 .Nm
 107 format.
 108 .It Ar sv4cpio
 109 SVR4 hex
 110 .Nm
 111 format.
 112 .It Ar tar
 113 Old tar format.
 114 .It Ar ustar
 115 POSIX ustar format.
 116 .El
 117 .It Fl L
 118 Follow symbolic links.
 119 .It Fl v
 120 Be verbose about operations.
 121 List filenames as they are written to the archive.
 122 .It Fl Fl xz
 123 Compress/decompress archive using
 124 .Xr xz 1
 125 format.
 126 .It Fl Z
 127 Compress archive using
 128 .Xr compress 1
 129 format.
 130 .It Fl z
 131 Compress/decompress archive using
 132 .Xr gzip 1
 133 format.
 134 .El
 135 .It Fl i , Fl Fl extract
 136 Restore files from an archive.
 137 Reads the archive file from
 138 standard input and extracts files matching the
 139 .Ar patterns
 140 that were specified on the command line.
 141 .Bl -tag -width Ds
 142 .It Fl b
 143 Do byte and word swapping after reading in data from the
 144 archive, for restoring archives created on systems with
 145 a different byte order.
 146 .It Fl B
 147 Set the block size of the archive being read to 5120 bytes.
 148 .It Fl c
 149 Expect the archive headers to be in ASCII format.
 150 .It Fl C Ar bytes
 151 Read archive written with a block size of
 152 .Ar bytes .
 153 .It Fl d , Fl Fl make-directories
 154 Create any intermediate directories as needed during
 155 restore.
 156 .It Fl E Ar file , Fl Fl pattern-file Ar file
 157 Read list of file name patterns to extract or list from
 158 .Ar file .
 159 .It Fl f , Fl Fl nonmatching
 160 Restore all files except those matching the
 161 .Ar patterns
 162 given on the command line.
 163 .It Fl F Ar archive , Fl Fl file Ar archive
 164 .It Fl I Ar archive
 165 Use the specified file as the input for the archive.
 166 .It Fl H Ar format , Fl Fl format Ar format
 167 Read an archive of the specified format.
 168 Recognized formats are:
 169 .Pp
 170 .Bl -tag -width sv4cpio -compact
 171 .It Ar bcpio
 172 Old binary
 173 .Nm
 174 format.
 175 .It Ar cpio
 176 Old octal character
 177 .Nm
 178 format.
 179 .It Ar sv4cpio
 180 SVR4 hex
 181 .Nm
 182 format.
 183 .It Ar tar
 184 Old tar format.
 185 .It Ar ustar
 186 POSIX ustar format.
 187 .El
 188 .It Fl m
 189 Restore modification times on files.
 190 .It Fl r , Fl Fl rename
 191 Rename restored files interactively.
 192 .It Fl s
 193 Swap bytes after reading data from the archive.
 194 .It Fl S , Fl Fl swap-halfwords
 195 Swap words after reading data from the archive.
 196 .It Fl t , Fl Fl list
 197 Only list the contents of the archive, no files or
 198 directories will be created.
 199 .It Fl u , Fl Fl unconditional
 200 Overwrite files even when the file in the archive is
 201 older than the one that will be overwritten.
 202 .It Fl v , Fl Fl verbose
 203 Be verbose about operations.
 204 List filenames as they are copied in from the archive.
 205 .It Fl z
 206 Uncompress archive using
 207 .Xr gzip 1
 208 format.
 209 .It Fl Z
 210 Uncompress archive using
 211 .Xr compress 1
 212 format.
 213 .It Fl 6
 214 Process old-style
 215 .Nm
 216 format archives.
 217 .El
 218 .It Fl p , Fl Fl pass-through
 219 Copy files from one location to another in a single pass.
 220 The list of files to copy are read from standard input and
 221 written out to a directory relative to the specified
 222 .Ar directory
 223 argument.
 224 .Bl -tag -width Ds
 225 .It Fl a
 226 Reset the access times on files that have been copied.
 227 .It Fl d
 228 Create any intermediate directories as needed to write
 229 the files at the new location.
 230 .It Fl l , Fl Fl link
 231 When possible, link files rather than creating an
 232 extra copy.
 233 .It Fl L , Fl Fl dereference
 234 Follow symbolic links.
 235 .It Fl m , Fl Fl preserve-modification-time
 236 Restore modification times on files.
 237 .It Fl u , Fl Fl unconditional
 238 Overwrite files even when the original file being copied is
 239 older than the one that will be overwritten.
 240 .It Fl v , Fl Fl verbose
 241 Be verbose about operations.
 242 List filenames as they are copied.
 243 .It Fl Fl force-local
 244 Do not interpret filenames that contain a
 245 .Sq \&:
 246 as remote files.
 247 .It Fl Fl insecure
 248 Normally
 249 .Nm
 250 ignores filenames that contain
 251 .Dq ..
 252 as a path component.
 253 With this option, files that contain
 254 .Dq ..
 255 can be processed.
 256 .El
 257 .El
 258 .Sh EXIT STATUS
 259 .Nm
 260 will exit with one of the following values:
 261 .Bl -tag -width 2n
 262 .It 0
 263 All files were processed successfully.
 264 .It 1
 265 An error occurred.
 266 .El
 267 .Pp
 268 Whenever
 269 .Nm
 270 cannot create a file or a link when extracting an archive or cannot
 271 find a file while writing an archive, or cannot preserve the user
 272 ID, group ID, file mode, or access and modification times when the
 273 .Fl p
 274 option is specified, a diagnostic message is written to standard
 275 error and a non-zero exit value will be returned, but processing
 276 will continue.
 277 In the case where
 278 .Nm
 279 cannot create a link to a file,
 280 .Nm
 281 will not create a second copy of the file.
 282 .Pp
 283 If the extraction of a file from an archive is prematurely terminated
 284 by a signal or error,
 285 .Nm
 286 may have only partially extracted the file the user wanted.
 287 Additionally, the file modes of extracted files and directories may
 288 have incorrect file bits, and the modification and access times may
 289 be wrong.
 290 .Pp
 291 If the creation of an archive is prematurely terminated by a signal
 292 or error,
 293 .Nm
 294 may have only partially created the archive which may violate the
 295 specific archive format specification.
 296 .Sh SEE ALSO
 297 .Xr pax 1 ,
 298 .Xr tar 1
 299 .Sh AUTHORS
 300 .An Keith Muller
 301 at the University of California, San Diego.
 302 .Sh BUGS
 303 The
 304 .Fl s
 305 and
 306 .Fl S
 307 options are currently not implemented.