1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2003-2007 Tim Kientzle 5.\" All rights reserved. 6.\" 7.Dd September 16, 2014 8.Dt CPIO 1 9.Os 10.Sh NAME 11.Nm cpio 12.Nd copy files to and from archives 13.Sh SYNOPSIS 14.Nm 15.Fl i 16.Op Ar options 17.Op Ar pattern ... 18.Op Ar < archive 19.Nm 20.Fl o 21.Op Ar options 22.Ar < name-list 23.Op Ar > archive 24.Nm 25.Fl p 26.Op Ar options 27.Ar dest-dir 28.Ar < name-list 29.Sh DESCRIPTION 30.Nm 31copies files between archives and directories. 32This implementation can extract from tar, pax, cpio, zip, jar, ar, 33and ISO 9660 cdrom images and can create tar, pax, cpio, ar, 34and shar archives. 35.Pp 36The first option to 37.Nm 38is a mode indicator from the following list: 39.Bl -tag -compact -width indent 40.It Fl i 41Input. 42Read an archive from standard input (unless overridden) and extract the 43contents to disk or (if the 44.Fl t 45option is specified) 46list the contents to standard output. 47If one or more file patterns are specified, only files matching 48one of the patterns will be extracted. 49.It Fl o 50Output. 51Read a list of filenames from standard input and produce a new archive 52on standard output (unless overridden) containing the specified items. 53.It Fl p 54Pass-through. 55Read a list of filenames from standard input and copy the files to the 56specified directory. 57.El 58.Sh OPTIONS 59Unless specifically stated otherwise, options are applicable in 60all operating modes. 61.Bl -tag -width indent 62.It Fl 0 , Fl Fl null 63Read filenames separated by NUL characters instead of newlines. 64This is necessary if any of the filenames being read might contain newlines. 65.It Fl 6 , Fl Fl pwb 66When reading a binary format archive, assume it's the earlier one, 67from the PWB variant of 6th Edition UNIX. 68When writing a cpio archive, use the PWB format. 69.It Fl 7 , Fl Fl binary 70(o mode only) 71When writing a cpio archive, use the (newer, non-PWB) binary format. 72.It Fl A 73(o mode only) 74Append to the specified archive. 75(Not yet implemented.) 76.It Fl a 77(o and p modes) 78Reset access times on files after they are read. 79.It Fl B 80(o mode only) 81Block output to records of 5120 bytes. 82.It Fl C Ar size 83(o mode only) 84Block output to records of 85.Ar size 86bytes. 87.It Fl c 88(o mode only) 89Use the old POSIX portable character format. 90Equivalent to 91.Fl Fl format Ar odc . 92.It Fl d , Fl Fl make-directories 93(i and p modes) 94Create directories as necessary. 95.It Fl E Ar file 96(i mode only) 97Read list of file name patterns from 98.Ar file 99to list and extract. 100.It Fl F Ar file , Fl Fl file Ar file 101Read archive from or write archive to 102.Ar file . 103.It Fl f Ar pattern 104(i mode only) 105Ignore files that match 106.Ar pattern . 107.It Fl H Ar format , Fl Fl format Ar format 108(o mode only) 109Produce the output archive in the specified format. 110Supported formats include: 111.Pp 112.Bl -tag -width "iso9660" -compact 113.It Ar cpio 114Synonym for 115.Ar odc . 116.It Ar newc 117The SVR4 portable cpio format. 118.It Ar odc 119The old POSIX.1 portable octet-oriented cpio format. 120.It Ar pax 121The POSIX.1 pax format, an extension of the ustar format. 122.It Ar ustar 123The POSIX.1 tar format. 124.El 125.Pp 126The default format is 127.Ar odc . 128See 129.Xr libarchive-formats 5 130for more complete information about the 131formats currently supported by the underlying 132.Xr libarchive 3 133library. 134.It Fl h , Fl Fl help 135Print usage information. 136.It Fl I Ar file 137Read archive from 138.Ar file . 139.It Fl i , Fl Fl extract 140Input mode. 141See above for description. 142.It Fl Fl insecure 143(i and p mode only) 144Disable security checks during extraction or copying. 145This allows extraction via symbolic links, absolute paths, 146and path names containing 147.Sq .. 148in the name. 149.It Fl J , Fl Fl xz 150(o mode only) 151Compress the file with xz-compatible compression before writing it. 152In input mode, this option is ignored; xz compression is recognized 153automatically on input. 154.It Fl j 155Synonym for 156.Fl y . 157.It Fl L 158(o and p modes) 159All symbolic links will be followed. 160Normally, symbolic links are archived and copied as symbolic links. 161With this option, the target of the link will be archived or copied instead. 162.It Fl l , Fl Fl link 163(p mode only) 164Create links from the target directory to the original files, 165instead of copying. 166.It Fl Fl lrzip 167(o mode only) 168Compress the resulting archive with 169.Xr lrzip 1 . 170In input mode, this option is ignored. 171.It Fl Fl lz4 172(o mode only) 173Compress the archive with lz4-compatible compression before writing it. 174In input mode, this option is ignored; lz4 compression is recognized 175automatically on input. 176.It Fl Fl zstd 177(o mode only) 178Compress the archive with zstd-compatible compression before writing it. 179In input mode, this option is ignored; zstd compression is recognized 180automatically on input. 181.It Fl Fl lzma 182(o mode only) 183Compress the file with lzma-compatible compression before writing it. 184In input mode, this option is ignored; lzma compression is recognized 185automatically on input. 186.It Fl Fl lzop 187(o mode only) 188Compress the resulting archive with 189.Xr lzop 1 . 190In input mode, this option is ignored. 191.It Fl Fl passphrase Ar passphrase 192The 193.Pa passphrase 194is used to extract or create an encrypted archive. 195Currently, zip is only a format that 196.Nm 197can handle encrypted archives. 198You shouldn't use this option unless you realize how insecure 199use of this option is. 200.It Fl m , Fl Fl preserve-modification-time 201(i and p modes) 202Set file modification time on created files to match 203those in the source. 204.It Fl n , Fl Fl numeric-uid-gid 205(i mode, only with 206.Fl t ) 207Display numeric uid and gid. 208By default, 209.Nm 210displays the user and group names when they are provided in the 211archive, or looks up the user and group names in the system 212password database. 213.It Fl Fl no-preserve-owner 214(i mode only) 215Do not attempt to restore file ownership. 216This is the default when run by non-root users. 217.It Fl O Ar file 218Write archive to 219.Ar file . 220.It Fl o , Fl Fl create 221Output mode. 222See above for description. 223.It Fl p , Fl Fl pass-through 224Pass-through mode. 225See above for description. 226.It Fl Fl preserve-owner 227(i mode only) 228Restore file ownership. 229This is the default when run by the root user. 230.It Fl Fl quiet 231Suppress unnecessary messages. 232.It Fl R Oo user Oc Ns Oo : Oc Ns Oo group Oc , Fl Fl owner Oo user Oc Ns Oo : Oc Ns Oo group Oc 233Set the owner and/or group on files in the output. 234If group is specified with no user 235(for example, 236.Fl R Ar :wheel ) 237then the group will be set but not the user. 238If the user is specified with a trailing colon and no group 239(for example, 240.Fl R Ar root: ) 241then the group will be set to the user's default group. 242If the user is specified with no trailing colon, then 243the user will be set but not the group. 244In 245.Fl i 246and 247.Fl p 248modes, this option can only be used by the super-user. 249(For compatibility, a period can be used in place of the colon.) 250.It Fl r 251(All modes.) 252Rename files interactively. 253For each file, a prompt is written to 254.Pa /dev/tty 255containing the name of the file and a line is read from 256.Pa /dev/tty . 257If the line read is blank, the file is skipped. 258If the line contains a single period, the file is processed normally. 259Otherwise, the line is taken to be the new name of the file. 260.It Fl t , Fl Fl list 261(i mode only) 262List the contents of the archive to stdout; 263do not restore the contents to disk. 264.It Fl u , Fl Fl unconditional 265(i and p modes) 266Unconditionally overwrite existing files. 267Ordinarily, an older file will not overwrite a newer file on disk. 268.It Fl V , Fl Fl dot 269Print a dot to stderr for each file as it is processed. 270Superseded by 271.Fl v . 272.It Fl v , Fl Fl verbose 273Print the name of each file to stderr as it is processed. 274With 275.Fl t , 276provide a detailed listing of each file. 277.It Fl Fl version 278Print the program version information and exit. 279.It Fl y 280(o mode only) 281Compress the archive with bzip2-compatible compression before writing it. 282In input mode, this option is ignored; 283bzip2 compression is recognized automatically on input. 284.It Fl Z 285(o mode only) 286Compress the archive with compress-compatible compression before writing it. 287In input mode, this option is ignored; 288compression is recognized automatically on input. 289.It Fl z 290(o mode only) 291Compress the archive with gzip-compatible compression before writing it. 292In input mode, this option is ignored; 293gzip compression is recognized automatically on input. 294.El 295.Sh EXIT STATUS 296.Ex -std 297.Sh ENVIRONMENT 298The following environment variables affect the execution of 299.Nm : 300.Bl -tag -width ".Ev BLOCKSIZE" 301.It Ev LANG 302The locale to use. 303See 304.Xr environ 7 305for more information. 306.It Ev TZ 307The timezone to use when displaying dates. 308See 309.Xr environ 7 310for more information. 311.El 312.Sh EXAMPLES 313The 314.Nm 315command is traditionally used to copy file hierarchies in conjunction 316with the 317.Xr find 1 318command. 319The first example here simply copies all files from 320.Pa src 321to 322.Pa dest : 323.Dl Nm find Pa src | Nm Fl pmud Pa dest 324.Pp 325By carefully selecting options to the 326.Xr find 1 327command and combining it with other standard utilities, 328it is possible to exercise very fine control over which files are copied. 329This next example copies files from 330.Pa src 331to 332.Pa dest 333that are more than 2 days old and whose names match a particular pattern: 334.Dl Nm find Pa src Fl mtime Ar +2 | Nm grep foo[bar] | Nm Fl pdmu Pa dest 335.Pp 336This example copies files from 337.Pa src 338to 339.Pa dest 340that are more than 2 days old and which contain the word 341.Do foobar Dc : 342.Dl Nm find Pa src Fl mtime Ar +2 | Nm xargs Nm grep -l foobar | Nm Fl pdmu Pa dest 343.Sh COMPATIBILITY 344The mode options i, o, and p and the options 345a, B, c, d, f, l, m, r, t, u, and v comply with SUSv2. 346.Pp 347The old POSIX.1 standard specified that only 348.Fl i , 349.Fl o , 350and 351.Fl p 352were interpreted as command-line options. 353Each took a single argument of a list of modifier 354characters. 355For example, the standard syntax allows 356.Fl imu 357but does not support 358.Fl miu 359or 360.Fl i Fl m Fl u , 361since 362.Ar m 363and 364.Ar u 365are only modifiers to 366.Fl i , 367they are not command-line options in their own right. 368The syntax supported by this implementation is backwards-compatible 369with the standard. 370For best compatibility, scripts should limit themselves to the 371standard syntax. 372.Sh SEE ALSO 373.Xr bzip2 1 , 374.Xr gzip 1 , 375.Xr mt 1 , 376.Xr pax 1 , 377.Xr tar 1 , 378.Xr libarchive 3 , 379.Xr cpio 5 , 380.Xr libarchive-formats 5 , 381.Xr tar 5 382.Sh STANDARDS 383There is no current POSIX standard for the cpio command; it appeared 384in 385.St -p1003.1-96 386but was dropped from 387.St -p1003.1-2001 . 388.Pp 389The cpio, ustar, and pax interchange file formats are defined by 390.St -p1003.1-2001 391for the pax command. 392.Sh HISTORY 393The original 394.Nm cpio 395and 396.Nm find 397utilities were written by Dick Haight 398while working in AT&T's Unix Support Group. 399They first appeared in 1977 in PWB/UNIX 1.0, the 400.Dq Programmer's Work Bench 401system developed for use within AT&T. 402They were first released outside of AT&T as part of System III Unix in 1981. 403As a result, 404.Nm cpio 405actually predates 406.Nm tar , 407even though it was not well-known outside of AT&T until some time later. 408.Pp 409This is a complete re-implementation based on the 410.Xr libarchive 3 411library. 412.Sh BUGS 413The cpio archive format has several basic limitations: 414It does not store user and group names, only numbers. 415As a result, it cannot be reliably used to transfer 416files between systems with dissimilar user and group numbering. 417Older cpio formats limit the user and group numbers to 41816 or 18 bits, which is insufficient for modern systems. 419The cpio archive formats cannot support files over 4 gigabytes, 420except for the 421.Dq odc 422variant, which can support files up to 8 gigabytes. 423