1.\" $OpenBSD: cpio.1,v 1.36 2020/01/16 16:46:46 schwarze 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.Dd $Mdocdate: January 16 2020 $ 27.Dt CPIO 1 28.Os 29.Sh NAME 30.Nm cpio 31.Nd copy file archives in and out 32.Sh SYNOPSIS 33.Nm cpio 34.Fl o 35.Op Fl AaBcjLvZz 36.Op Fl C Ar bytes 37.Op Fl F Ar archive 38.Op Fl H Ar format 39.Op Fl O Ar archive 40.No \*(Lt Ar name-list 41.Op \*(Gt Ar archive 42.Nm cpio 43.Fl i 44.Op Fl 6BbcdfjmrSstuvZz 45.Op Fl C Ar bytes 46.Op Fl E Ar file 47.Op Fl F Ar archive 48.Op Fl H Ar format 49.Op Fl I Ar archive 50.Op Ar pattern ... 51.Op \*(Lt Ar archive 52.Nm cpio 53.Fl p 54.Op Fl adLlmuv 55.Ar destination-directory 56.No \*(Lt Ar name-list 57.Sh DESCRIPTION 58The 59.Nm 60command copies files to and from a 61.Nm 62archive. 63.Pp 64The options are as follows: 65.Bl -tag -width Ds 66.It Fl o 67Create an archive. 68Reads the list of files to store in the 69archive from standard input, and writes the archive on standard 70output. 71.Bl -tag -width Ds 72.It Fl A 73Append to the specified archive. 74.It Fl a 75Reset the access times on files that have been copied to the 76archive. 77.It Fl B 78Set block size of output to 5120 bytes. 79.It Fl C Ar bytes 80Set the block size of output to 81.Ar bytes . 82.It Fl c 83Use ASCII format for 84.Nm 85header for portability. 86.It Fl F Ar archive 87Use the specified file as the input for the archive. 88.It Fl H Ar format 89Write the archive in the specified format. 90Recognized formats are: 91.Pp 92.Bl -tag -width sv4cpio -compact 93.It Ar bcpio 94Old binary 95.Nm 96format. 97.It Ar cpio 98Old octal character 99.Nm 100format. 101.It Ar sv4cpio 102SVR4 hex 103.Nm 104format. 105.It Ar tar 106Old tar format. 107.It Ar ustar 108POSIX ustar format. 109.El 110.It Fl j 111Compress archive using the bzip2 format. 112The bzip2 utility must be installed separately. 113.It Fl L 114Follow symbolic links. 115.It Fl O Ar archive 116Use the specified file name as the archive to write to. 117.It Fl v 118Be verbose about operations. 119List filenames as they are written to the archive. 120.It Fl Z 121Compress archive using 122.Xr compress 1 123format. 124.It Fl z 125Compress archive using 126.Xr gzip 1 127format. 128.El 129.It Fl i 130Restore files from an archive. 131Reads the archive file from 132standard input and extracts files matching the 133.Ar patterns 134that were specified on the command line. 135.Bl -tag -width Ds 136.It Fl 6 137Process old-style 138.Nm 139format archives. 140.It Fl B 141Set the block size of the archive being read to 5120 bytes. 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 C Ar bytes 147Read archive written with a block size of 148.Ar bytes . 149.It Fl c 150Expect the archive headers to be in ASCII format. 151.It Fl d 152Create any intermediate directories as needed during 153restore. 154.It Fl E Ar file 155Read list of file name patterns to extract or list from 156.Ar file . 157.It Fl F Ar archive , Fl I Ar archive 158Use the specified file as the input for the archive. 159.It Fl f 160Restore all files except those matching the 161.Ar patterns 162given on the command line. 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 j 186Uncompress archive using the bzip2 format. 187The bzip2 utility must be installed separately. 188.It Fl m 189Restore modification times on files. 190.It Fl r 191Rename restored files interactively. 192.It Fl S 193Swap words after reading data from the archive. 194.It Fl s 195Swap bytes after reading data from the archive. 196.It Fl t 197Only list the contents of the archive, no files or 198directories will be created. 199.It Fl u 200Overwrite files even when the file in the archive is 201older than the one that will be overwritten. 202.It Fl v 203Be verbose about operations. 204List filenames as they are copied in from the archive. 205.It Fl Z 206Uncompress archive using 207.Xr compress 1 208format. 209.It Fl z 210Uncompress archive using 211.Xr gzip 1 212format. 213.El 214.It Fl p 215Copy files from one location to another in a single pass. 216The list of files to copy are read from standard input and 217written out to a directory relative to the specified 218.Ar directory 219argument. 220.Bl -tag -width Ds 221.It Fl a 222Reset the access times on files that have been copied. 223.It Fl d 224Create any intermediate directories as needed to write 225the files at the new location. 226.It Fl L 227Follow symbolic links. 228.It Fl l 229When possible, link files rather than creating an 230extra copy. 231.It Fl m 232Restore modification times on files. 233.It Fl u 234Overwrite files even when the original file being copied is 235older than the one that will be overwritten. 236.It Fl v 237Be verbose about operations. 238List filenames as they are copied. 239.El 240.El 241.Sh ENVIRONMENT 242.Bl -tag -width Ds 243.It Ev TMPDIR 244Path in which to store temporary files. 245.El 246.Sh EXIT STATUS 247The 248.Nm 249utility exits with one of the following values: 250.Pp 251.Bl -tag -width Ds -offset indent -compact 252.It 0 253All files were processed successfully. 254.It 1 255An error occurred. 256.El 257.Sh DIAGNOSTICS 258Whenever 259.Nm 260cannot create a file or a link when extracting an archive or cannot 261find a file while writing an archive, or cannot preserve the user 262ID, group ID, file mode, or access and modification times when the 263.Fl p 264option is specified, a diagnostic message is written to standard 265error and a non-zero exit value will be returned, but processing 266will continue. 267In the case where 268.Nm 269cannot create a link to a file, 270.Nm 271will not create a second copy of the file. 272.Pp 273If the extraction of a file from an archive is prematurely terminated 274by a signal or error, 275.Nm 276may have only partially extracted the file the user wanted. 277Additionally, the file modes of extracted files and directories may 278have incorrect file bits, and the modification and access times may 279be wrong. 280.Pp 281If the creation of an archive is prematurely terminated by a signal 282or error, 283.Nm 284may have only partially created the archive, which may violate the 285specific archive format specification. 286.Sh SEE ALSO 287.Xr pax 1 , 288.Xr tar 1 289.Sh AUTHORS 290.An Keith Muller 291at the University of California, San Diego. 292.Sh CAVEATS 293Different file formats have different maximum file sizes. 294It is recommended that a format such as cpio or ustar 295be used for larger files. 296.Bl -column "File format" "Maximum file size" -offset indent 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 305The 306.Fl s 307and 308.Fl S 309options are currently not implemented. 310