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] [--message=mes‐
21 sage][--null] [--reset-access-time] [--verbose] [--dot] [--append]
22 [--block-size=blocks] [--dereference] [--io-size=bytes] [--rsh-com‐
23 mand=command] [--help] [--version] < name-list [> archive]
24 Copy-in mode
26 In copy-in mode, cpio copies files out of an archive or lists the ar‐
28 chive contents. It reads the archive from the standard input. Any
29 non-option command line arguments are shell globbing patterns; only
30 files in the archive whose names match one or more of those patterns
31 are copied from the archive. Unlike in the shell, an initial `.' in a
32 filename does match a wildcard at the start of a pattern, and a `/' in
33 a filename can match wildcards. If no patterns are given, all files
34 are extracted. see “Options”.
35 cpio {-i|--extract} [-bcdfmnrtsuvBSV] [-C bytes] [-E file] [-H format]
37 [-M message] [-R [user][:.][group]] [-I [[user@]host:]archive] [-F
38 [[user@]host:]archive] [--file=[[user@]host:]archive] [--make-directo‐
39 ries] [--nonmatching] [--preserve-modification-time] [--numeric-uid-
40 gid] [--rename] [-t|--list] [--swap-bytes] [--swap] [--dot] [--uncondi‐
41 tional] [--verbose] [--block-size=blocks] [--swap-halfwords] [--io-
42 size=bytes] [--pattern-file=file] [--format=format]
43 [--owner=[user][:.][group]] [--no-preserve-owner] [--message=message]
44 [--force-local] [--no-absolute-filenames] [--absolute-filenames]
45 [--sparse] [--only-verify-crc] [--to-stdout] [--quiet] [--rsh-com‐
46 mand=command] [--help] [--version] [pattern...] [< archive]
47 Copy-pass mode
49 In copy-pass mode, cpio copies files from one directory tree to
51 another, combining the copy-out and copy-in steps without actually
52 using an archive. It reads the list of files to copy from the standard
53 input; the directory into which it will copy them is given as a non-
54 option argument. see “Options”.
55 cpio {-p|--pass-through} [-0adlmuvLV] [-R [user][:.][group]] [--null]
57 [--reset-access-time] [--make-directories] [--link] [--quiet] [--pre‐
58 serve-modification-time] [--unconditional] [--verbose] [--dot]
59 [--dereference] [--owner=[user][:.][group]] [--no-preserve-owner]
60 [--sparse] [--help] [--version] destination-directory < name-list
61
63 GNU cpio is a tool for creating and extracting archives, or copying
64 files from one place to another. It handles a number of cpio formats
65 as well as reading and writing tar files.
66 Following archive formats are supported: binary, old ASCII, new ASCII,
68 crc, HPUX binary, HPUX old ASCII, old tar, and POSIX.1 tar. The tar
69 format is provided for compatibility with the tar program. By default,
70 cpio creates binary format archives, for compatibility with older cpio
71 programs. When extracting from archives, cpio automatically recognizes
72 which kind of archive it is reading and can read archives created on
73 machines with a different byte-order.
74
76 `-0, --null'
77 Read a list of filenames terminated by a null character, instead
78 of a newline, so that files whose names contain newlines can be
79 archived. GNU find is one way to produce a list of null-termi‐
80 nated filenames. This option may be used in copy-out and copy-
81 pass modes.
82 `-a, --reset-access-time'
84 Reset the access times of files after reading them, so that it
85 does not look like they have just been read.
86 `-A, --append'
88 Append to an existing archive. Only works in copy-out mode.
89 The archive must be a disk file specified with the -O or -F
90 (-file) option.
91 `-b, --swap'
93 Swap both halfwords of words and bytes of halfwords in the data.
94 Equivalent to -sS. This option may be used in copy-in mode.
95 Use this option to convert 32-bit integers between big-endian
96 and little-endian machines.
97 `-B' Set the I/O block size to 5120 bytes. Initially the block size
99 is 512 bytes.
100 `--block-size=BLOCK-SIZE'
102 Set the I/O block size to BLOCK-SIZE * 512 bytes.
103 `-c' Identical to “-H newc”, use the new (SVR4) portable format. If
105 you wish the old portable (ASCII) archive format, use “-H odc”
106 instead.
107 `-C IO-SIZE, --io-size=IO-SIZE'
109 Set the I/O block size to IO-SIZE bytes.
110 `-d, --make-directories'
112 Create leading directories where needed.
113 `-E FILE, --pattern-file=FILE'
115 Read additional patterns specifying filenames to extract or list
116 from FILE. The lines of FILE are treated as if they had been
117 non-option arguments to cpio. This option is used in copy-in
118 mode,
119 `-f, --nonmatching'
121 Only copy files that do not match any of the given patterns.
122 `-F, --file=archive'
124 Archive filename to use instead of standard input or output. To
125 use a tape drive on another machine as the archive, use a file‐
126 name that starts with `HOSTNAME:'. The hostname can be preceded
127 by a username and an `@' to access the remote tape drive as that
128 user, if you have permission to do so (typically an entry in
129 that user's `~/.rhosts' file).
130 `--force-local'
132 With -F, -I, or -O, take the archive file name to be a local
133 file even if it contains a colon, which would ordinarily indi‐
134 cate a remote host name.
135 `-H FORMAT, --format=FORMAT'
137 Use archive format FORMAT. The valid formats are listed below;
138 the same names are also recognized in all-caps. The default in
139 copy-in mode is to automatically detect the archive format, and
140 in copy-out mode is `bin'.
141 `bin' The obsolete binary format.
143 `odc' The old (POSIX.1) portable format.
145 `newc' The new (SVR4) portable format, which supports file systems hav‐
147 ing more than 65536 i-nodes.
148 `crc' The new (SVR4) portable format with a checksum added.
150 `tar' The old tar format.
152 `ustar'
154 The POSIX.1 tar format. Also recognizes GNU tar archives, which
155 are similar but not identical.
156 `hpbin'
158 The obsolete binary format used by HPUX's cpio (which stores
159 device files differently).
160 `hpodc'
162 The portable format used by HPUX's cpio (which stores device
163 files differently).
164 `-i, --extract'
166 Run in copy-in mode. see “Copy-in mode”.
167 `-I archive'
169 Archive filename to use instead of standard input. To use a
170 tape drive on another machine as the archive, use a filename
171 that starts with `HOSTNAME:'. The hostname can be preceded by a
172 username and an `@' to access the remote tape drive as that
173 user, if you have permission to do so (typically an entry in
174 that user's `~/.rhosts' file).
175 `-k' Ignored; for compatibility with other versions of cpio.
177 `-l, --link'
179 Link files instead of copying them, when possible.
180 `-L, --dereference'
182 Copy the file that a symbolic link points to, rather than the
183 symbolic link itself.
184 `-m, --preserve-modification-time'
186 Retain previous file modification times when creating files.
187 `-M MESSAGE, --message=MESSAGE'
189 Print MESSAGE when the end of a volume of the backup media (such
190 as a tape or a floppy disk) is reached, to prompt the user to
191 insert a new volume. If MESSAGE contains the string “%d”, it is
192 replaced by the current volume number (starting at 1).
193 `-n, --numeric-uid-gid'
195 Show numeric UID and GID instead of translating them into names
196 when using the `--verbose option'.
197 `--no-absolute-filenames'
199 Create all files relative to the current directory in copy-in
200 mode, even if they have an absolute file name in the archive.
201 `--absolute-filenames' (default)
203 Do not strip leading file name components that contain “..” and
204 leading slashes from file names in copy-in mode
205 `--no-preserve-owner'
207 Do not change the ownership of the files; leave them owned by
208 the user extracting them. This is the default for non-root
209 users, so that users on System V don't inadvertently give away
210 files. This option can be used in copy-in mode and copy-pass
211 mode
212 `-o, --create'
214 Run in copy-out mode. see “Copy-out mode”.
215 `-O archive'
217 Archive filename to use instead of standard output. To use a
218 tape drive on another machine as the archive, use a filename
219 that starts with `HOSTNAME:'. The hostname can be preceded by a
220 username and an `@' to access the remote tape drive as that
221 user, if you have permission to do so (typically an entry in
222 that user's `~/.rhosts' file).
223 `--only-verify-crc'
225 Verify the CRC's of each file in the archive, when reading a CRC
226 format archive. Don't actually extract the files.
227 `-p, --pass-through'
229 Run in copy-pass mode. see “Copy-pass mode”.
230 `--quiet'
232 Do not print the number of blocks copied.
233 `-r, --rename'
235 Interactively rename files.
236 `-R [user][:.][group], --owner [user][:.][group]'
238 Set the ownership of all files created to the specified user
239 and/or group in copy-out and copy-pass modes. Either the user,
240 the group, or both, must be present. If the group is omitted
241 but the “:” or “.” separator is given, use the given user's
242 login group. Only the super-user can change files' ownership.
243 `--rsh-command=COMMAND'
245 Notifies cpio that is should use COMMAND to communicate with
246 remote devices.
247 `-s, --swap-bytes'
249 Swap the bytes of each halfword (pair of bytes) in the
250 files.This option can be used in copy-in mode.
251 `-S, --swap-halfwords'
253 Swap the halfwords of each word (4 bytes) in the files. This
254 option may be used in copy-in mode.
255 `--sparse'
257 Write files with large blocks of zeros as sparse files. This
258 option is used in copy-in and copy-pass modes.
259 `-t, --list'
261 Print a table of contents of the input.
262 `--to-stdout'
264 Extract files to standard output. This option may be used in
265 copy-in mode.
266 `-u, --unconditional'
268 Replace all files, without asking whether to replace existing
269 newer files with older files.
270 `-v, --verbose'
272 List the files processed, or with `-t', give an `ls -l' style
273 table of contents listing. In a verbose table of contents of a
274 ustar archive, user and group names in the archive that do not
275 exist on the local system are replaced by the names that corre‐
276 spond locally to the numeric UID and GID stored in the archive.
277 `-V, --dot'
279 Print a `.' for each file processed.
280 `--version'
282 Print the cpio program version number and exit.
283
285 When creating an archive, cpio takes the list of files to be processed
286 from the standard input, and then sends the archive to the standard
287 output, or to the device defined by the `-F' option. Usually find or
288 ls is used to provide this list to the standard input. In the follow‐
289 ing example you can see the possibilities for archiving the contents of
290 a single directory.
291 % ls | cpio -ov > directory.cpio
293 The `-o' option creates the archive, and the `-v' option prints the
295 names of the files archived as they are added. Notice that the options
296 can be put together after a single `-' or can be placed separately on
297 the command line. The `>' redirects the cpio output to the file
298 `directory.cpio'.
299 If you wanted to archive an entire directory tree, the find command can
301 provide the file list to cpio:
302 % find . -print -depth | cpio -ov > tree.cpio
304 This will take all the files in the current directory, the directories
306 below and place them in the archive tree.cpio. Again the `-o' creates
307 an archive, and the `-v' option shows you the name of the files as they
308 are archived. see “Copy-out mode”. Using the `.' in the find state‐
309 ment will give you more flexibility when doing restores, as it will
310 save file names with a relative path vice a hard wired, absolute path.
311 The `-depth' option forces `find' to print of the entries in a direc‐
312 tory before printing the directory itself. This limits the effects of
313 restrictive directory permissions by printing the directory entries in
314 a directory before the directory name itself.
315 Extracting an archive requires a bit more thought because cpio will not
317 create directories by default. Another characteristic, is it will not
318 overwrite existing files unless you tell it to.
319 % cpio -iv < directory.cpio
321 This will retrieve the files archived in the file directory.cpio and
323 place them in the present directory. The `-i' option extracts the ar‐
324 chive and the `-v' shows the file names as they are extracted. If you
325 are dealing with an archived directory tree, you need to use the `-d'
326 option to create directories as necessary, something like:
327 % cpio -idv < tree.cpio
329 This will take the contents of the archive tree.cpio and extract it to
331 the current directory. If you try to extract the files on top of files
332 of the same name that already exist (and have the same or later modifi‐
333 cation time) cpio will not extract the file unless told to do so by the
334 -u option. see “Copy-in mode”.
335 In copy-pass mode, cpio copies files from one directory tree to
337 another, combining the copy-out and copy-in steps without actually
338 using an archive. It reads the list of files to copy from the standard
339 input; the directory into which it will copy them is given as a non-
340 option argument. see “Copy-pass mode”.
341 % find . -depth -print0 | cpio --null -pvd new-dir
343 The example shows copying the files of the present directory, and sub-
345 directories to a new directory called new-dir. Some new options are
346 the `-print0' available with GNU find, combined with the `--null'
347 option of cpio. These two options act together to send file names
348 between find and cpio, even if special characters are embedded in the
349 file names. Another is `-p', which tells cpio to pass the files it
350 finds to the directory `new-dir'.
351
354 The GNU folks, in general, abhor man pages, and create info documents
355 instead. The maintainer of cpio falls into this category. Thus this
356 man page may not be complete, nor current, and was included in the Red
357 Hat CVS tree because man is a great tool :).
358
360 Please report bugs via https://bugzilla.redhat.com.
361
363 The full documentation for cpio is maintained as a Texinfo manual. If
364 the info and cpio programs are properly installed at your site, the
365 command
366 info cpio
368 should give you access to the complete manual. The online copy of the
370 documentation is available at the following address:
371 http://www.gnu.org/software/cpio/manual
373 CPIO(1L)