Debian Codegraph @

upstream/fedora-44/man1/cpio.1

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