1CPIO(1L) CPIO(1L)
2
6 cpio - copy files to and from archives
7
9 Copy-out mode
10 In copy-out mode, cpio copies files into an archive. It reads a list
12 of filenames, one per line, on the standard input, and writes the ar‐
13 chive onto the standard output. A typical way to generate the list of
14 filenames is with the find command; you should give find the -depth
15 option to minimize problems with permissions on directories that are
16 unreadable. see “Options”.
17 cpio {-o|--create} [-0acvABLV] [-C bytes] [-H format] [-M message] [-O
19 [[user@]host:]archive] [-F [[user@]host:]archive]
20 [--file=[[user@]host:]archive] [--format=format] [--warning=FLAG]
21 [--message=message][--null] [--reset-access-time] [--verbose] [--dot]
22 [--append] [--block-size=blocks] [--dereference] [--io-size=bytes]
23 [--rsh-command=command] [--license] [--usage] [--help] [--version] <
24 name-list [> archive]
25 Copy-in mode
27 In copy-in mode, cpio copies files out of an archive or lists the ar‐
29 chive contents. It reads the archive from the standard input. Any
30 non-option command line arguments are shell globbing patterns; only
31 files in the archive whose names match one or more of those patterns
32 are copied from the archive. Unlike in the shell, an initial `.' in a
33 filename does match a wildcard at the start of a pattern, and a `/' in
34 a filename can match wildcards. If no patterns are given, all files
35 are extracted. see “Options”.
36 cpio {-i|--extract} [-bcdfmnrtsuvBSV] [-C bytes] [-E file] [-H format]
38 [-M message] [-R [user][:.][group]] [-I [[user@]host:]archive] [-F
39 [[user@]host:]archive] [--file=[[user@]host:]archive] [--make-directo‐
40 ries] [--nonmatching] [--preserve-modification-time] [--numeric-uid-
41 gid] [--rename] [-t|--list] [--swap-bytes] [--swap] [--dot] [--warn‐
42 ing=FLAG] [--unconditional] [--verbose] [--block-size=blocks] [--swap-
43 halfwords] [--io-size=bytes] [--pattern-file=file] [--format=format]
44 [--owner=[user][:.][group]] [--no-preserve-owner] [--message=message]
45 [--force-local] [--no-absolute-filenames] [--absolute-filenames]
46 [--sparse] [--only-verify-crc] [--to-stdout] [--quiet] [--rsh-com‐
47 mand=command] [--license] [--usage] [--help] [--version] [pattern...]
48 [< archive]
49 Copy-pass mode
51 In copy-pass mode, cpio copies files from one directory tree to
53 another, combining the copy-out and copy-in steps without actually
54 using an archive. It reads the list of files to copy from the standard
55 input; the directory into which it will copy them is given as a non-
56 option argument. see “Options”.
57 cpio {-p|--pass-through} [-0adlmuvLV] [-R [user][:.][group]] [--null]
59 [--reset-access-time] [--make-directories] [--link] [--quiet] [--pre‐
60 serve-modification-time] [--unconditional] [--verbose] [--dot] [--warn‐
61 ing=FLAG] [--dereference] [--owner=[user][:.][group]] [--no-preserve-
62 owner] [--sparse] [--license] [--usage] [--help] [--version] destina‐
63 tion-directory < name-list
64
66 GNU cpio is a tool for creating and extracting archives, or copying
67 files from one place to another. It handles a number of cpio formats
68 as well as reading and writing tar files.
69 Following archive formats are supported: binary, old ASCII, new ASCII,
71 crc, HPUX binary, HPUX old ASCII, old tar, and POSIX.1 tar. The tar
72 format is provided for compatibility with the tar program. By default,
73 cpio creates binary format archives, for compatibility with older cpio
74 programs. When extracting from archives, cpio automatically recognizes
75 which kind of archive it is reading and can read archives created on
76 machines with a different byte-order.
77
79 `-0, --null'
80 Read a list of filenames terminated by a null character, instead
81 of a newline, so that files whose names contain newlines can be
82 archived. GNU find is one way to produce a list of null-termi‐
83 nated filenames. This option may be used in copy-out and copy-
84 pass modes.
85 `-a, --reset-access-time'
87 Reset the access times of files after reading them, so that it
88 does not look like they have just been read.
89 `-A, --append'
91 Append to an existing archive. Only works in copy-out mode.
92 The archive must be a disk file specified with the -O or -F
93 (-file) option.
94 `-b, --swap'
96 Swap both halfwords of words and bytes of halfwords in the data.
97 Equivalent to -sS. This option may be used in copy-in mode.
98 Use this option to convert 32-bit integers between big-endian
99 and little-endian machines.
100 `-B' Set the I/O block size to 5120 bytes. Initially the block size
102 is 512 bytes.
103 `--block-size=BLOCK-SIZE'
105 Set the I/O block size to BLOCK-SIZE * 512 bytes.
106 `-c' Identical to “-H newc”, use the new (SVR4) portable format. If
108 you wish the old portable (ASCII) archive format, use “-H odc”
109 instead.
110 `-C IO-SIZE, --io-size=IO-SIZE'
112 Set the I/O block size to IO-SIZE bytes.
113 `-d, --make-directories'
115 Create leading directories where needed.
116 `--device-independent, --reproducible'
118 Create reproducible archives. This is equivalent to
119 --ignore-devno --renumber-inodes.
120 `-E FILE, --pattern-file=FILE'
122 Read additional patterns specifying filenames to extract or list
123 from FILE. The lines of FILE are treated as if they had been
124 non-option arguments to cpio. This option is used in copy-in
125 mode,
126 `-f, --nonmatching'
128 Only copy files that do not match any of the given patterns.
129 `-F, --file=archive'
131 Archive filename to use instead of standard input or output. To
132 use a tape drive on another machine as the archive, use a file‐
133 name that starts with `HOSTNAME:'. The hostname can be preceded
134 by a username and an `@' to access the remote tape drive as that
135 user, if you have permission to do so (typically an entry in
136 that user's `~/.rhosts' file).
137 `--force-local'
139 With -F, -I, or -O, take the archive file name to be a local
140 file even if it contains a colon, which would ordinarily indi‐
141 cate a remote host name.
142 `-H FORMAT, --format=FORMAT'
144 Use archive format FORMAT. The valid formats are listed below;
145 the same names are also recognized in all-caps. The default in
146 copy-in mode is to automatically detect the archive format, and
147 in copy-out mode is `bin'.
148 `bin' The obsolete binary format.
150 `odc' The old (POSIX.1) portable format.
152 `newc' The new (SVR4) portable format, which supports file systems hav‐
154 ing more than 65536 i-nodes.
155 `crc' The new (SVR4) portable format with a checksum (Sum32) added.
157 `tar' The old tar format.
159 `ustar'
161 The POSIX.1 tar format. Also recognizes GNU tar archives, which
162 are similar but not identical.
163 `hpbin'
165 The obsolete binary format used by HPUX's cpio (which stores
166 device files differently).
167 `hpodc'
169 The portable format used by HPUX's cpio (which stores device
170 files differently).
171 `-i, --extract'
173 Run in copy-in mode. see “Copy-in mode”.
174 `-I archive'
176 Archive filename to use instead of standard input. To use a
177 tape drive on another machine as the archive, use a filename
178 that starts with `HOSTNAME:'. The hostname can be preceded by a
179 username and an `@' to access the remote tape drive as that
180 user, if you have permission to do so (typically an entry in
181 that user's `~/.rhosts' file).
182 `--ignore-devno'
184 Store 0 in the device number field of each archive member,
185 instead of the actual device number.
186 `-k' Ignored; for compatibility with other versions of cpio.
188 `-l, --link'
190 Link files instead of copying them, when possible.
191 `-L, --dereference'
193 Copy the file that a symbolic link points to, rather than the
194 symbolic link itself.
195 `-m, --preserve-modification-time'
197 Retain previous file modification times when creating files.
198 `-M MESSAGE, --message=MESSAGE'
200 Print MESSAGE when the end of a volume of the backup media (such
201 as a tape or a floppy disk) is reached, to prompt the user to
202 insert a new volume. If MESSAGE contains the string “%d”, it is
203 replaced by the current volume number (starting at 1).
204 `-n, --numeric-uid-gid'
206 Show numeric UID and GID instead of translating them into names
207 when using the `--verbose option'.
208 `--no-absolute-filenames'
210 Create all files relative to the current directory in copy-in
211 mode, even if they have an absolute file name in the archive.
212 `--absolute-filenames' (default)
214 Do not strip leading file name components that contain “..” and
215 leading slashes from file names in copy-in mode
216 `--no-preserve-owner'
218 Do not change the ownership of the files; leave them owned by
219 the user extracting them. This is the default for non-root
220 users, so that users on System V don't inadvertently give away
221 files. This option can be used in copy-in mode and copy-pass
222 mode
223 `-o, --create'
225 Run in copy-out mode. see “Copy-out mode”.
226 `-O archive'
228 Archive filename to use instead of standard output. To use a
229 tape drive on another machine as the archive, use a filename
230 that starts with `HOSTNAME:'. The hostname can be preceded by a
231 username and an `@' to access the remote tape drive as that
232 user, if you have permission to do so (typically an entry in
233 that user's `~/.rhosts' file).
234 `--only-verify-crc'
236 Verify the Sum32 checksum's of each file in the archive, when
237 reading a crc format archive. Don't actually extract the files.
238 `-p, --pass-through'
240 Run in copy-pass mode. see “Copy-pass mode”.
241 `--quiet'
243 Do not print the number of blocks copied.
244 `-r, --rename'
246 Interactively rename files.
247 `--renumber-inodes'
249 Renumber inodes when storing them in the archive.
250 `-R [user][:.][group], --owner [user][:.][group]'
252 Set the ownership of all files created to the specified user
253 and/or group in copy-out and copy-pass modes. Either the user,
254 the group, or both, must be present. If the group is omitted
255 but the “:” or “.” separator is given, use the given user's
256 login group. Only the super-user can change files' ownership.
257 `--rsh-command=COMMAND'
259 Notifies cpio that is should use COMMAND to communicate with
260 remote devices.
261 `-s, --swap-bytes'
263 Swap the bytes of each halfword (pair of bytes) in the
264 files.This option can be used in copy-in mode.
265 `-S, --swap-halfwords'
267 Swap the halfwords of each word (4 bytes) in the files. This
268 option may be used in copy-in mode.
269 `--sparse'
271 Write files with large blocks of zeros as sparse files. This
272 option is used in copy-in and copy-pass modes.
273 `-t, --list'
275 Print a table of contents of the input.
276 `--to-stdout'
278 Extract files to standard output. This option may be used in
279 copy-in mode.
280 `-u, --unconditional'
282 Replace all files, without asking whether to replace existing
283 newer files with older files.
284 `-v, --verbose'
286 List the files processed, or with `-t', give an `ls -l' style
287 table of contents listing. In a verbose table of contents of a
288 ustar archive, user and group names in the archive that do not
289 exist on the local system are replaced by the names that corre‐
290 spond locally to the numeric UID and GID stored in the archive.
291 `-V, --dot'
293 Print a `.' for each file processed.
294 `-W, --warning'
296 Control warning display. Currently FLAG is one of 'none', 'trun‐
297 cate', 'all'. Multiple options accumulate.
298 `--license'
300 Print license and exit.
301 `?, --help'
303 Give a help page similar to this manpage.
304 `--usage'
306 Give a short usage message.
307 `--version'
309 Print the cpio program version number and exit.
310
313 When creating an archive, cpio takes the list of files to be processed
314 from the standard input, and then sends the archive to the standard
315 output, or to the device defined by the `-F' option. Usually find or
316 ls is used to provide this list to the standard input. In the follow‐
317 ing example you can see the possibilities for archiving the contents of
318 a single directory.
319 % ls | cpio -ov > directory.cpio
321 The `-o' option creates the archive, and the `-v' option prints the
323 names of the files archived as they are added. Notice that the options
324 can be put together after a single `-' or can be placed separately on
325 the command line. The `>' redirects the cpio output to the file
326 `directory.cpio'.
327 If you wanted to archive an entire directory tree, the find command can
329 provide the file list to cpio:
330 % find . -print -depth | cpio -ov > tree.cpio
332 This will take all the files in the current directory, the directories
334 below and place them in the archive tree.cpio. Again the `-o' creates
335 an archive, and the `-v' option shows you the name of the files as they
336 are archived. see “Copy-out mode”. Using the `.' in the find state‐
337 ment will give you more flexibility when doing restores, as it will
338 save file names with a relative path vice a hard wired, absolute path.
339 The `-depth' option forces `find' to print of the entries in a direc‐
340 tory before printing the directory itself. This limits the effects of
341 restrictive directory permissions by printing the directory entries in
342 a directory before the directory name itself.
343 Extracting an archive requires a bit more thought because cpio will not
345 create directories by default. Another characteristic, is it will not
346 overwrite existing files unless you tell it to.
347 % cpio -iv < directory.cpio
349 This will retrieve the files archived in the file directory.cpio and
351 place them in the present directory. The `-i' option extracts the ar‐
352 chive and the `-v' shows the file names as they are extracted. If you
353 are dealing with an archived directory tree, you need to use the `-d'
354 option to create directories as necessary, something like:
355 % cpio -idv < tree.cpio
357 This will take the contents of the archive tree.cpio and extract it to
359 the current directory. If you try to extract the files on top of files
360 of the same name that already exist (and have the same or later modifi‐
361 cation time) cpio will not extract the file unless told to do so by the
362 -u option. see “Copy-in mode”.
363 In copy-pass mode, cpio copies files from one directory tree to
365 another, combining the copy-out and copy-in steps without actually
366 using an archive. It reads the list of files to copy from the standard
367 input; the directory into which it will copy them is given as a non-
368 option argument. see “Copy-pass mode”.
369 % find . -depth -print0 | cpio --null -pvd new-dir
371 The example shows copying the files of the present directory, and sub-
373 directories to a new directory called new-dir. Some new options are
374 the `-print0' available with GNU find, combined with the `--null'
375 option of cpio. These two options act together to send file names
376 between find and cpio, even if special characters are embedded in the
377 file names. Another is `-p', which tells cpio to pass the files it
378 finds to the directory `new-dir'.
379
382 The GNU folks, in general, abhor man pages, and create info documents
383 instead. The maintainer of cpio falls into this category. Thus this
384 man page may not be complete, nor current, and was included in the Red
385 Hat CVS tree because man is a great tool :).
386
388 Please report bugs via https://bugzilla.redhat.com.
389
391 The full documentation for cpio is maintained as a Texinfo manual. If
392 the info and cpio programs are properly installed at your site, the
393 command
394 info cpio
396 should give you access to the complete manual. The online copy of the
398 documentation is available at the following address:
399 http://www.gnu.org/software/cpio/manual
401 CPIO(1L)