doc/text/bsdcpio.1.txt

   1 CPIO(1)                   BSD General Commands Manual                  CPIO(1)
   2
   3 1mNAME0m
   4      1mcpio 22m— copy files to and from archives
   5
   6 1mSYNOPSIS0m
   7      1mcpio -i 22m[4moptions24m] [4mpattern24m 4m...24m] [4m<24m 4marchive24m]
   8      1mcpio -o 22m[4moptions24m] 4m<24m 4mname-list24m [4m>24m 4marchive24m]
   9      1mcpio -p 22m[4moptions24m] 4mdest-dir24m 4m<24m 4mname-list0m
  10
  11 1mDESCRIPTION0m
  12      1mcpio 22mcopies files between archives and directories.  This implementation
  13      can extract from tar, pax, cpio, zip, jar, ar, and ISO 9660 cdrom images
  14      and can create tar, pax, cpio, ar, and shar archives.
  15
  16      The first option to 1mcpio 22mis a mode indicator from the following list:
  17      1m-i      22mInput.  Read an archive from standard input (unless overridden)
  18              and extract the contents to disk or (if the 1m-t 22moption is speci‐
  19              fied) list the contents to standard output.  If one or more file
  20              patterns are specified, only files matching one of the patterns
  21              will be extracted.
  22      1m-o      22mOutput.  Read a list of filenames from standard input and produce
  23              a new archive on standard output (unless overridden) containing
  24              the specified items.
  25      1m-p      22mPass-through.  Read a list of filenames from standard input and
  26              copy the files to the specified directory.
  27
  28 1mOPTIONS0m
  29      Unless specifically stated otherwise, options are applicable in all oper‐
  30      ating modes.
  31
  32      1m-022m, 1m--null0m
  33              Read filenames separated by NUL characters instead of newlines.
  34              This is necessary if any of the filenames being read might con‐
  35              tain newlines.
  36
  37      1m-A      22m(o mode only) Append to the specified archive.  (Not yet imple‐
  38              mented.)
  39
  40      1m-a      22m(o and p modes) Reset access times on files after they are read.
  41
  42      1m-B      22m(o mode only) Block output to records of 5120 bytes.
  43
  44      1m-C 4m22msize0m
  45              (o mode only) Block output to records of 4msize24m bytes.
  46
  47      1m-c      22m(o mode only) Use the old POSIX portable character format.
  48              Equivalent to 1m--format 4m22modc24m.
  49
  50      1m-d22m, 1m--make-directories0m
  51              (i and p modes) Create directories as necessary.
  52
  53      1m-E 4m22mfile0m
  54              (i mode only) Read list of file name patterns from 4mfile24m to list
  55              and extract.
  56
  57      1m-F 4m22mfile24m, 1m--file 4m22mfile0m
  58              Read archive from or write archive to 4mfile24m.
  59
  60      1m-f 4m22mpattern0m
  61              (i mode only) Ignore files that match 4mpattern24m.
  62
  63      1m-H 4m22mformat24m, 1m--format 4m22mformat0m
  64              (o mode only) Produce the output archive in the specified format.
  65              Supported formats include:
  66
  67              4mcpio24m     Synonym for 4modc24m.
  68              4mnewc24m     The SVR4 portable cpio format.
  69              4modc24m      The old POSIX.1 portable octet-oriented cpio format.
  70              4mpax24m      The POSIX.1 pax format, an extension of the ustar for‐
  71                       mat.
  72              4mustar24m    The POSIX.1 tar format.
  73
  74              The default format is 4modc24m.  See libarchive-formats(5) for more
  75              complete information about the formats currently supported by the
  76              underlying libarchive(3) library.
  77
  78      1m-h22m, 1m--help0m
  79              Print usage information.
  80
  81      1m-I 4m22mfile0m
  82              Read archive from 4mfile24m.
  83
  84      1m-i22m, 1m--extract0m
  85              Input mode.  See above for description.
  86
  87      1m--insecure0m
  88              (i and p mode only) Disable security checks during extraction or
  89              copying.  This allows extraction via symbolic links, absolute
  90              paths, and path names containing ‘..’ in the name.
  91
  92      1m-J22m, 1m--xz0m
  93              (o mode only) Compress the file with xz-compatible compression
  94              before writing it.  In input mode, this option is ignored; xz
  95              compression is recognized automatically on input.
  96
  97      1m-j      22mSynonym for 1m-y22m.
  98
  99      1m-L      22m(o and p modes) All symbolic links will be followed.  Normally,
 100              symbolic links are archived and copied as symbolic links.  With
 101              this option, the target of the link will be archived or copied
 102              instead.
 103
 104      1m-l22m, 1m--link0m
 105              (p mode only) Create links from the target directory to the orig‐
 106              inal files, instead of copying.
 107
 108      1m--lrzip0m
 109              (o mode only) Compress the resulting archive with lrzip(1).  In
 110              input mode, this option is ignored.
 111
 112      1m--lz4   22m(o mode only) Compress the archive with lz4-compatible compres‐
 113              sion before writing it.  In input mode, this option is ignored;
 114              lz4 compression is recognized automatically on input.
 115
 116      1m--lzma  22m(o mode only) Compress the file with lzma-compatible compression
 117              before writing it.  In input mode, this option is ignored; lzma
 118              compression is recognized automatically on input.
 119
 120      1m--lzop  22m(o mode only) Compress the resulting archive with lzop(1).  In
 121              input mode, this option is ignored.
 122
 123      1m--passphrase 4m22mpassphrase0m
 124              The 4mpassphrase24m is used to extract or create an encrypted archive.
 125              Currently, zip is only a format that 1mcpio 22mcan handle encrypted
 126              archives.  You shouldn't use this option unless you realize how
 127              insecure use of this option is.
 128
 129      1m-m22m, 1m--preserve-modification-time0m
 130              (i and p modes) Set file modification time on created files to
 131              match those in the source.
 132
 133      1m-n22m, 1m--numeric-uid-gid0m
 134              (i mode, only with 1m-t22m) Display numeric uid and gid.  By default,
 135              1mcpio 22mdisplays the user and group names when they are provided in
 136              the archive, or looks up the user and group names in the system
 137              password database.
 138
 139      1m--no-preserve-owner0m
 140              (i mode only) Do not attempt to restore file ownership.  This is
 141              the default when run by non-root users.
 142
 143      1m-O 4m22mfile0m
 144              Write archive to 4mfile24m.
 145
 146      1m-o22m, 1m--create0m
 147              Output mode.  See above for description.
 148
 149      1m-p22m, 1m--pass-through0m
 150              Pass-through mode.  See above for description.
 151
 152      1m--preserve-owner0m
 153              (i mode only) Restore file ownership.  This is the default when
 154              run by the root user.
 155
 156      1m--quiet0m
 157              Suppress unnecessary messages.
 158
 159      1m-R 22m[user][:][group], 1m--owner 22m[user][:][group]
 160              Set the owner and/or group on files in the output.  If group is
 161              specified with no user (for example, 1m-R 4m22m:wheel24m) then the group
 162              will be set but not the user.  If the user is specified with a
 163              trailing colon and no group (for example, 1m-R 4m22mroot:24m) then the
 164              group will be set to the user's default group.  If the user is
 165              specified with no trailing colon, then the user will be set but
 166              not the group.  In 1m-i 22mand 1m-p 22mmodes, this option can only be used
 167              by the super-user.  (For compatibility, a period can be used in
 168              place of the colon.)
 169
 170      1m-r      22m(All modes.)  Rename files interactively.  For each file, a
 171              prompt is written to 4m/dev/tty24m containing the name of the file and
 172              a line is read from 4m/dev/tty24m.  If the line read is blank, the
 173              file is skipped.  If the line contains a single period, the file
 174              is processed normally.  Otherwise, the line is taken to be the
 175              new name of the file.
 176
 177      1m-t22m, 1m--list0m
 178              (i mode only) List the contents of the archive to stdout; do not
 179              restore the contents to disk.
 180
 181      1m-u22m, 1m--unconditional0m
 182              (i and p modes) Unconditionally overwrite existing files.  Ordi‐
 183              narily, an older file will not overwrite a newer file on disk.
 184
 185      1m-V22m, 1m--dot0m
 186              Print a dot to stderr for each file as it is processed.  Super‐
 187              seded by 1m-v22m.
 188
 189      1m-v22m, 1m--verbose0m
 190              Print the name of each file to stderr as it is processed.  With
 191              1m-t22m, provide a detailed listing of each file.
 192
 193      1m--version0m
 194              Print the program version information and exit.
 195
 196      1m-y      22m(o mode only) Compress the archive with bzip2-compatible compres‐
 197              sion before writing it.  In input mode, this option is ignored;
 198              bzip2 compression is recognized automatically on input.
 199
 200      1m-Z      22m(o mode only) Compress the archive with compress-compatible com‐
 201              pression before writing it.  In input mode, this option is
 202              ignored; compression is recognized automatically on input.
 203
 204      1m-z      22m(o mode only) Compress the archive with gzip-compatible compres‐
 205              sion before writing it.  In input mode, this option is ignored;
 206              gzip compression is recognized automatically on input.
 207
 208 1mEXIT STATUS0m
 209      The 1mcpio 22mutility exits 0 on success, and >0 if an error occurs.
 210
 211 1mENVIRONMENT0m
 212      The following environment variables affect the execution of 1mcpio22m:
 213
 214      LANG       The locale to use.  See environ(7) for more information.
 215
 216      TZ         The timezone to use when displaying dates.  See environ(7) for
 217                 more information.
 218
 219 1mEXAMPLES0m
 220      The 1mcpio 22mcommand is traditionally used to copy file hierarchies in con‐
 221      junction with the find(1) command.  The first example here simply copies
 222      all files from 4msrc24m to 4mdest24m:
 223            1mfind 4m22msrc24m | 1mcpio -pmud 4m22mdest0m
 224
 225      By carefully selecting options to the find(1) command and combining it
 226      with other standard utilities, it is possible to exercise very fine con‐
 227      trol over which files are copied.  This next example copies files from
 228      4msrc24m to 4mdest24m that are more than 2 days old and whose names match a partic‐
 229      ular pattern:
 230            1mfind 4m22msrc24m 1m-mtime 4m22m+224m | 1mgrep foo[bar] 22m| 1mcpio -pdmu 4m22mdest0m
 231
 232      This example copies files from 4msrc24m to 4mdest24m that are more than 2 days old
 233      and which contain the word “foobar”:
 234            1mfind 4m22msrc24m 1m-mtime 4m22m+224m | 1mxargs grep -l foobar 22m| 1mcpio -pdmu 4m22mdest0m
 235
 236 1mCOMPATIBILITY0m
 237      The mode options i, o, and p and the options a, B, c, d, f, l, m, r, t,
 238      u, and v comply with SUSv2.
 239
 240      The old POSIX.1 standard specified that only 1m-i22m, 1m-o22m, and 1m-p 22mwere inter‐
 241      preted as command-line options.  Each took a single argument of a list of
 242      modifier characters.  For example, the standard syntax allows 1m-imu 22mbut
 243      does not support 1m-miu 22mor 1m-i -m -u22m, since 4mm24m and 4mu24m are only modifiers to
 244      1m-i22m, they are not command-line options in their own right.  The syntax
 245      supported by this implementation is backwards-compatible with the stan‐
 246      dard.  For best compatibility, scripts should limit themselves to the
 247      standard syntax.
 248
 249 1mSEE ALSO0m
 250      bzip2(1), tar(1), gzip(1), mt(1), pax(1), libarchive(3), cpio(5),
 251      libarchive-formats(5), tar(5)
 252
 253 1mSTANDARDS0m
 254      There is no current POSIX standard for the cpio command; it appeared in
 255      ISO/IEC 9945-1:1996 (“POSIX.1”) but was dropped from IEEE Std 1003.1-2001
 256      (“POSIX.1”).
 257
 258      The cpio, ustar, and pax interchange file formats are defined by IEEE Std
 259      1003.1-2001 (“POSIX.1”) for the pax command.
 260
 261 1mHISTORY0m
 262      The original 1mcpio 22mand 1mfind 22mutilities were written by Dick Haight while
 263      working in AT&T's Unix Support Group.  They first appeared in 1977 in
 264      PWB/UNIX 1.0, the “Programmer's Work Bench” system developed for use
 265      within AT&T.  They were first released outside of AT&T as part of System
 266      III Unix in 1981.  As a result, 1mcpio 22mactually predates 1mtar22m, even though
 267      it was not well-known outside of AT&T until some time later.
 268
 269      This is a complete re-implementation based on the libarchive(3) library.
 270
 271 1mBUGS0m
 272      The cpio archive format has several basic limitations: It does not store
 273      user and group names, only numbers.  As a result, it cannot be reliably
 274      used to transfer files between systems with dissimilar user and group
 275      numbering.  Older cpio formats limit the user and group numbers to 16 or
 276      18 bits, which is insufficient for modern systems.  The cpio archive for‐
 277      mats cannot support files over 4 gigabytes, except for the “odc” variant,
 278      which can support files up to 8 gigabytes.
 279
 280 BSD                           September 16, 2014                           BSD