1CPIO(1L) CPIO(1L)
2
6 cpio - copy files to and from archives
7
9 The cpio utility is considered LEGACY based on POSIX specification.
10 Users are encouraged to use other archiving tools for archive creation.
11 If you decided to use cpio, you should almost always force cpio to use
13 the ustar format in copy-out mode by the -H option (cpio -o -H ustar).
14 This is because the ustar format is well defined in POSIX specification
15 and thus readable by wide range of other archiving tools (including tar
16 e.g.).
17 By default, GNU cpio uses (for historical reasons) the very old binary
19 format ('bin') which has significant problems nowadays, e.g. with stor‐
20 ing big inode numbers (see the Red Hat bug #952313).
21 Note also that these days the modern 'pax' archive format should be
23 considered as the default -- but this format is not implemented in GNU
24 cpio. You should, again, consider using other archivers (e.g. 'tar
25 --format=pax').
26
29 Copy-out mode
30 In copy-out mode, cpio copies files into an archive. It reads a list
32 of filenames, one per line, on the standard input, and writes the ar‐
33 chive onto the standard output. A typical way to generate the list of
34 filenames is with the find command; you should give find the -depth
35 option to minimize problems with permissions on directories that are
36 unreadable. see “Options”.
37 cpio {-o|--create} [-0acvABLV] [-C bytes] [-H format] [-D DIR] [-M mes‐
39 sage] [-O [[user@]host:]archive] [-F [[user@]host:]archive]
40 [--file=[[user@]host:]archive] [--format=format] [--warning=FLAG]
41 [--message=message][--null] [--reset-access-time] [--verbose] [--dot]
42 [--append] [--block-size=blocks] [--dereference] [--io-size=bytes]
43 [--rsh-command=command] [--license] [--usage] [--help] [--version] <
44 name-list [> archive]
45 Copy-in mode
47 In copy-in mode, cpio copies files out of an archive or lists the ar‐
49 chive contents. It reads the archive from the standard input. Any
50 non-option command line arguments are shell globbing patterns; only
51 files in the archive whose names match one or more of those patterns
52 are copied from the archive. Unlike in the shell, an initial `.' in a
53 filename does match a wildcard at the start of a pattern, and a `/' in
54 a filename can match wildcards. If no patterns are given, all files
55 are extracted. see “Options”.
56 cpio {-i|--extract} [-bcdfmnrtsuvBSV] [-C bytes] [-E file] [-H format]
58 [-D DIR] [-M message] [-R [user][:.][group]] [-I [[user@]host:]archive]
59 [-F [[user@]host:]archive] [--file=[[user@]host:]archive] [--make-
60 directories] [--nonmatching] [--preserve-modification-time] [--numeric-
61 uid-gid] [--rename] [-t|--list] [--swap-bytes] [--swap] [--dot]
62 [--warning=FLAG] [--unconditional] [--verbose] [--block-size=blocks]
63 [--swap-halfwords] [--io-size=bytes] [--pattern-file=file] [--for‐
64 mat=format] [--owner=[user][:.][group]] [--no-preserve-owner] [--mes‐
65 sage=message] [--force-local] [--no-absolute-filenames] [--abso‐
66 lute-filenames] [--sparse] [--only-verify-crc] [--to-stdout] [--quiet]
67 [--ignore-devno] [--renumber-inodes] [--device-independent] [--repro‐
68 ducible] [--rsh-command=command] [--license] [--usage] [--help] [--ver‐
69 sion] [pattern...] [< archive]
70 Copy-pass mode
72 In copy-pass mode, cpio copies files from one directory tree to
74 another, combining the copy-out and copy-in steps without actually
75 using an archive. It reads the list of files to copy from the standard
76 input; the directory into which it will copy them is given as a non-
77 option argument. see “Options”.
78 cpio {-p|--pass-through} [-0adlmuvLV] [-R [user][:.][group]] [-D DIR]
80 [--null] [--reset-access-time] [--make-directories] [--link] [--quiet]
81 [--preserve-modification-time] [--unconditional] [--verbose] [--dot]
82 [--warning=FLAG] [--dereference] [--owner=[user][:.][group]] [--no-pre‐
83 serve-owner] [--sparse] [--license] [--usage] [--help] [--version]
84 destination-directory < name-list
85
87 GNU cpio is a tool for creating and extracting archives, or copying
88 files from one place to another. It handles a number of cpio formats
89 as well as reading and writing tar files.
90 Following archive formats are supported: binary, old ASCII, new ASCII,
92 crc, HPUX binary, HPUX old ASCII, old tar, and POSIX.1 tar. The tar
93 format is provided for compatibility with the tar program. By default,
94 cpio creates binary format archives, for compatibility with older cpio
95 programs. When extracting from archives, cpio automatically recognizes
96 which kind of archive it is reading and can read archives created on
97 machines with a different byte-order.
98 Main operation mode:
100 -i, --extract
101 Extract files from an archive (run in copy-in mode)
102 -o, --create
104 Create the archive (run in copy-out mode)
105 -p, --pass-through
107 Run in copy-pass mode
108 -t, --list
110 Print a table of contents of the input
111 Operation modifiers valid in any mode:
113 --block-size=BLOCK-SIZE
114 Set the I/O block size to BLOCK-SIZE * 512 bytes
115 -B Set the I/O block size to 5120 bytes. Initially the block size
117 is 512 bytes.
118 -c Identical to "-H newc", use the new (SVR4) portable format. If
120 you wish the old portable (ASCII) archive format, use "-H odc"
121 instead.
122 -C, --io-size=NUMBER
124 Set the I/O block size to the given NUMBER of bytes
125 -D, --directory=DIR
127 Change to directory DIR
128 --force-local
130 With -F, -I, or -O, take the archive file name to be a local
131 file even if it contains a colon, which would ordinarily indi‐
132 cate a remote host name.
133 -H, --format=FORMAT
135 Use given archive FORMAT. The valid formats are listed below;
136 the same names are also recognized in all-caps. The default in
137 copy-in mode is to automatically detect the archive format, and
138 in copy-out mode is `bin'.
139 `bin' The obsolete binary format.
141 `odc' The old (POSIX.1) portable format.
143 `newc' The new (SVR4) portable format, which supports file systems hav‐
145 ing more than 65536 i-nodes.
146 `crc' The new (SVR4) portable format with a checksum (Sum32) added.
148 `tar' The old tar format.
150 `ustar'
152 The POSIX.1 tar format. Also recognizes GNU tar archives, which
153 are similar but not identical.
154 `hpbin'
156 The obsolete binary format used by HPUX's cpio (which stores
157 device files differently).
158 `hpodc'
160 The portable format used by HPUX's cpio (which stores device
161 files differently).
162 --quiet
164 Do not print the number of blocks copied
165 -R, --owner=[USER][:.][GROUP]
167 Set the ownership of all files created to the specified USER
168 and/or GROUP. Either the user, the group, or both, must be
169 present. If the group is omitted but the “:” or “.” separator
170 is given, use the given user's login group. Only the super-user
171 can change files' ownership in copy-in mode.
172 -v, --verbose
174 List the files processed, or with `-t', give an `ls -l' style
175 table of contents listing. In a verbose table of contents of a
176 ustar archive, user and group names in the archive that do not
177 exist on the local system are replaced by the names that corre‐
178 spond locally to the numeric UID and GID stored in the archive.
179 -V, --dot
181 Print a "." for each file processed
182 -W, --warning=FLAG
184 Control warning display. Currently FLAG is one of 'none', 'trun‐
185 cate', 'all'. Multiple options accumulate.
186 Operation modifiers valid in copy-in and copy-out modes:
188 -F, --file=[[USER@]HOST:]FILE-NAME
189 Use this FILE-NAME instead of standard input or output. Optional
190 USER and HOST specify the user and host names in case of a
191 remote archive
192 -M, --message=STRING
194 Print STRING when the end of a volume of the backup media (such
195 as a tape or a floppy disk) is reached, to prompt the user to
196 insert a new volume. If STRING contains the string “%d”, it is
197 replaced by the current volume number (starting at 1).
198 --rsh-command=COMMAND
200 Use COMMAND instead of rsh (typically /usr/bin/ssh)
201 Operation modifiers valid only in copy-in mode:
203 -b, --swap
204 Swap both halfwords of words and bytes of halfwords in the data.
205 Equivalent to -sS Use this option to convert 32-bit integers
206 between big-endian and little-endian machines.
207 -f, --nonmatching
209 Only copy files that do not match any of the given patterns
210 -I [[USER@]HOST:]FILE-NAME
212 Archive filename to use instead of standard input. Optional
213 USER and HOST specify the user and host names in case of a
214 remote archive
215 -n, --numeric-uid-gid
217 In the verbose table of contents listing, show numeric UID and
218 GID
219 -r, --rename
221 Interactively rename files
222 -s, --swap-bytes
224 Swap the bytes of each halfword in the files
225 -S, --swap-halfwords
227 Swap the halfwords of each word (4 bytes) in the files
228 --to-stdout
230 Extract files to standard output
231 -E, --pattern-file=FILE
233 Read additional patterns specifying filenames to extract or list
234 from FILE
235 --only-verify-crc
237 When reading a CRC format archive, only verify the checksum of
238 each file in the archive, don't actually extract the files
239 Operation modifiers valid only in copy-out mode:
241 -A, --append
242 Append to an existing archive. The archive must be a disk file
243 specified with the -O or -F (-file) option.
244 --device-independent, --reproducible
246 Create device-independent (reproducible) archives
247 --ignore-devno
249 Don't store device numbers
250 -O [[USER@]HOST:]FILE-NAME
252 Archive filename to use instead of standard output. Optional
253 USER and HOST specify the user and host names in case of a
254 remote archive
255 --renumber-inodes
257 Renumber inodes
258 Operation modifiers valid only in copy-pass mode:
260 -l, --link
261 Link files instead of copying them, when possible
262 Operation modifiers valid in copy-in and copy-out modes:
264 --absolute-filenames
265 Do not strip file system prefix components from the file names
266 --no-absolute-filenames
268 Create all files relative to the current directory
269 Operation modifiers valid in copy-out and copy-pass modes:
271 -0, --null
272 Filenames in the list are delimited by null characters instead
273 of newlines, so that files whose names contain newlines can be
274 archived. GNU find is one way to produce a list of null-termi‐
275 nated filenames.
276 -a, --reset-access-time
278 Reset the access times of files after reading them, so that it
279 does not look like they have just been read.
280 -L, --dereference
282 Dereference symbolic links (copy the files that they point
283 to instead of copying the links).
284 Operation modifiers valid in copy-in and copy-pass modes:
286 -d, --make-directories
287 Create leading directories where needed
288 -m, --preserve-modification-time
290 Retain previous file modification times when creating files
291 --no-preserve-owner
293 Do not change the ownership of the files; leave them owned by
294 the user extracting them. This is the default for non-root
295 users, so that users on System V don't inadvertently give away
296 files. This option can be used in copy-in mode and copy-pass
297 mode
298 --sparse
300 Write files with large blocks of zeros as sparse files
301 -u, --unconditional
303 Replace all files unconditionally
304 -?, --help
306 give this help list
307 --usage
309 give a short usage message
310 --version
312 print program version
313 Mandatory or optional arguments to long options are also mandatory or
315 optional for any corresponding short options.
316
319 When creating an archive, cpio takes the list of files to be processed
320 from the standard input, and then sends the archive to the standard
321 output, or to the device defined by the `-F' option. Usually find or
322 ls is used to provide this list to the standard input. In the follow‐
323 ing example you can see the possibilities for archiving the contents of
324 a single directory.
325 % ls | cpio -ov > directory.cpio
327 The `-o' option creates the archive, and the `-v' option prints the
329 names of the files archived as they are added. Notice that the options
330 can be put together after a single `-' or can be placed separately on
331 the command line. The `>' redirects the cpio output to the file
332 `directory.cpio'.
333 If you wanted to archive an entire directory tree, the find command can
335 provide the file list to cpio:
336 % find . -print -depth | cpio -ov > tree.cpio
338 This will take all the files in the current directory, the directories
340 below and place them in the archive tree.cpio. Again the `-o' creates
341 an archive, and the `-v' option shows you the name of the files as they
342 are archived. see “Copy-out mode”. Using the `.' in the find state‐
343 ment will give you more flexibility when doing restores, as it will
344 save file names with a relative path vice a hard wired, absolute path.
345 The `-depth' option forces `find' to print of the entries in a direc‐
346 tory before printing the directory itself. This limits the effects of
347 restrictive directory permissions by printing the directory entries in
348 a directory before the directory name itself.
349 Extracting an archive requires a bit more thought because cpio will not
351 create directories by default. Another characteristic, is it will not
352 overwrite existing files unless you tell it to.
353 % cpio -iv < directory.cpio
355 This will retrieve the files archived in the file directory.cpio and
357 place them in the present directory. The `-i' option extracts the ar‐
358 chive and the `-v' shows the file names as they are extracted. If you
359 are dealing with an archived directory tree, you need to use the `-d'
360 option to create directories as necessary, something like:
361 % cpio -idv < tree.cpio
363 This will take the contents of the archive tree.cpio and extract it to
365 the current directory. If you try to extract the files on top of files
366 of the same name that already exist (and have the same or later modifi‐
367 cation time) cpio will not extract the file unless told to do so by the
368 -u option. see “Copy-in mode”.
369 In copy-pass mode, cpio copies files from one directory tree to
371 another, combining the copy-out and copy-in steps without actually
372 using an archive. It reads the list of files to copy from the standard
373 input; the directory into which it will copy them is given as a non-
374 option argument. see “Copy-pass mode”.
375 % find . -depth -print0 | cpio --null -pvd new-dir
377 The example shows copying the files of the present directory, and sub-
379 directories to a new directory called new-dir. Some new options are
380 the `-print0' available with GNU find, combined with the `--null'
381 option of cpio. These two options act together to send file names
382 between find and cpio, even if special characters are embedded in the
383 file names. Another is `-p', which tells cpio to pass the files it
384 finds to the directory `new-dir'.
385
389 Written by Phil Nelson, David MacKenzie, John Oleynick, and Sergey
390 Poznyakoff.
391
393 Report bugs to <bug-cpio@gnu.org>. Report bugs in this manual page via
394 https://bugzilla.redhat.com.
395
397 Copyright © 2015 Free Software Foundation, Inc. License GPLv3+: GNU
398 GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
399 This is free software: you are free to change and redistribute it.
400 There is NO WARRANTY, to the extent permitted by law.
401
403 The full documentation for cpio is maintained as a Texinfo manual. If
404 the info and cpio programs are properly installed at your site, the
405 command
406 info cpio
408 should give you access to the complete manual.
410 The online copy of the documentation is available at the following
412 address:
413 http://www.gnu.org/software/cpio/manual
415 CPIO(1L)