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