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