Debian Codegraph @

upstream/mageia-cauldron/man1/cpio.1

raw
1 .\" This file is part of GNU cpio. -*- nroff -*-
2 .\" Copyright 2014-2025 Free Software Foundation, Inc.
3 .\"
4 .\" GNU cpio is free software; you can redistribute it and/or modify
5 .\" it under the terms of the GNU General Public License as published by
6 .\" the Free Software Foundation; either version 3 of the License, or
7 .\" (at your option) any later version.
8 .\"
9 .\" GNU cpio is distributed in the hope that it will be useful,
10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 .\" GNU General Public License for more details.
13 .\"
14 .\" You should have received a copy of the GNU General Public License
15 .\" along with GNU cpio. If not, see <http://www.gnu.org/licenses/>.
16 .TH CPIO 1 "March 14, 2025" "CPIO" "GNU CPIO"
17 .SH NAME
18 cpio \- copy files to and from archives
19 .SH SYNOPSIS
20 .nh
21 .na
22 .B cpio
23 {\fB\-o\fR|\fB\-\-create\fR} [\fB\-0acvABLV\fR] [\fB\-C\fR \fIBYTES\fR]
24 [\fB\-H\fR \fIFORMAT\fR] [\fB\-M\fR \fIMESSAGE\fR]
25 [\fB\-O\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
26 [\fB\-F\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
27 [\fB\-\-file=\fR[[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
28 [\fB\-\-format=\fIFORMAT\fR] [\fB\-\-message=\fIMESSAGE\fR]
29 [\fB\-\-null\fR] [\fB\-\-reset\-access\-time\fR] [\fB\-\-verbose\fR]
30 [\fB\-\-dot\fR] [\fB\-\-append\fR]
31 [\fB\-\-block\-size=\fIblocks\fR] [\fB\-\-dereference\fR]
32 [\fB\-\-io\-size=\fIBYTES\fR] [\fB\-\-quiet\fR]
33 [\fB\-\-force\-local\fR] [\fB\-\-rsh\-command=\fICOMMAND\fR]
34 \fB<\fR \fIname-list\fR [\fB>\fR \fIarchive\fR]
35 .sp
36 .B cpio
37 {\fB\-i\fR|\fB\-\-extract\fR} [\fB\-bcdfmnrtsuvBSV\fR] [\fB\-C\fR \fIBYTES\fR]
38 [\fB\-E\fR \fIFILE\fR] [\fB\-H\fR \fIFORMAT\fR]
39 [\fB\-M\fR \fIMESSAGE\fR] [\fB\-R\fR [\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]]
40 [\fB\-I\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
41 [\fB\-F\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
42 [\fB\-\-file=\fR[[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
43 [\fB\-\-make\-directories\fR] [\fB\-\-nonmatching\fR]
44 [\fB\-\-preserve\-modification\-time\fR] [\fB\-\-numeric\-uid\-gid\fR]
45 [\fB\-\-rename\fR] [\fB\-\-list\fR] [\fB\-\-swap\-bytes\fR]
46 [\fB\-\-swap\fR] [\fB\-\-dot\fR] [\fB\-\-unconditional\fR]
47 [\fB\-\-verbose\fR] [\fB\-\-block\-size=\fIBLOCKS\fR]
48 [\fB\-\-swap\-halfwords\fR] [\fB\-\-io\-size=\fIBYTES\fR]
49 [\fB\-\-pattern\-file=\fIFILE\fR] [\fB\-\-format=\fIFORMAT\fR]
50 [\fB\-\-owner=\fR[\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]]
51 [\fB\-\-no\-preserve\-owner\fR] [\fB\-\-message=\fIMESSAGE\fR]
52 [\fB\-\-force\-local\fR] [\fB\-\-no\-absolute\-filenames\fR] [\fB\-\-sparse\fR]
53 [\fB\-\-only\-verify\-crc\fR] [\fB\-\-to\-stdout\fR] [\fB\-\-quiet\fR]
54 [\fB\-\-rsh\-command=\fICOMMAND\fR]
55 [\fIpattern\fR...] [\fB<\fR \fIarchive\fR]
56 .sp
57 .B cpio
58 {\fB\-p\fR|\fB\-\-pass\-through\fR} [\fB\-0adlmuvLV\fR]
59 [\fB\-R\fR [\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]]
60 [\fB\-\-null\fR] [\fB\-\-reset\-access\-time\fR]
61 [\fB\-\-make\-directories\fR] [\fB\-\-link\fR] [\fB\-\-quiet\fR]
62 [\fB\-\-preserve\-modification\-time] [\fB\-\-unconditional\fR]
63 [\fB\-\-verbose\fR] [\fB\-\-dot\fR] [\fB\-\-dereference\fR]
64 [\fB\-\-owner=\fR[\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]]
65 [\fB\-\-no\-preserve\-owner\fR] [\fB\-\-sparse\fR]
66 \fIdestination-directory\fR \fB<\fR \fIname-list\fR
67 .sp
68 .B cpio
69 {\fB\-?\fR|\fB\-\-help\fR|\fB\-\-usage\fR|\fB\-\-version\fR}
70 .ad
71 .hy
72 .SH NOTE
73 This manpage is a short description of GNU \fBcpio\fR. For a detailed
74 discussion, including examples and usage recommendations, refer to the
75 \fBGNU Cpio Manual\fR available in texinfo format. If the \fBinfo\fR
76 reader and the cpio documentation are properly installed on your
77 system, the command
78 .PP
79 .RS +4
80 .B info cpio
81 .RE
82 .PP
83 should give you access to the complete manual.
84 .PP
85 You can also view the manual using the info mode in
86 .BR emacs (1),
87 or find it in various formats online at
88 .PP
89 .RS +4
90 .B http://www.gnu.org/software/cpio/manual
91 .RE
92 .PP
93 If any discrepancies occur between this manpage and the
94 \fBGNU Cpio Manual\fR, the later shall be considered the authoritative
95 source.
96 .SH DESCRIPTION
97 GNU \fBcpio\fR copies files between archives and directories. It
98 supports the following archive formats: old binary cpio, old portable
99 cpio, SVR4 cpio with and without checksum, HP cpio, and various tar
100 formats.
101 .PP
102 The operation mode is requested by one of the following options:
103 .TP
104 .BR \-o ", " \-\-create
105 Copy-out. Read a list of file names from the standard input and
106 create on the standard output (unless overridden by the \fB\-\-file\fR
107 option) an archive containing these files.
108 .TP
109 .BR \-i ", " \-\-extract
110 Copy-in. Read the archive from standard input (or from the file
111 supplied with the \fB\-\-file\fR option) and extract files from it, or
112 (if the \fB\-t\fR option is given) list its contents to the standard
113 output. If one or more \fIpattern\fRs are supplied, read or list only
114 files matching these patterns. The \fB\-t\fR option alone implies
115 \fB\-i\fR.
116 .TP
117 .BR \-p ", " \-\-pass\-through
118 Pass-through. Read a list of file names from the standard input and
119 copy them to the specified directory.
120 .TP
121 .BR \-? ", " \-\-help
122 Give a short help summary and exit.
123 .TP
124 .B \-\-usage
125 Print a short usage message and exit.
126 .TP
127 .B \-\-version
128 Print program version and exit.
129 .SH OPTIONS
130 .SS Operation modifiers valid in any mode
131 .TP
132 \fB\-\-block\-size=\fIBLOCK-SIZE\fR
133 Set the I/O block size to \fIBLOCK-SIZE\fR * 512 bytes.
134 .TP
135 .B \-B
136 Set the I/O block size to 5120 bytes.
137 .TP
138 .B \-c
139 Use the old portable (ASCII) archive format. This is the same as
140 \fB\-H odc\fR.
141 .TP
142 \fB\-C\fR, \fB\-\-io\-size=\fINUMBER\fR
143 Set the I/O block size to the given \fINUMBER\fR of bytes.
144 .TP
145 \fB\-D\fR, \fB\-\-directory=\fIDIR\fR
146 Change to directory \fIDIR\fR.
147 .TP
148 .B \-\-force\-local
149 Archive file is local, even if its name contains colons.
150 .TP
151 \fB\-H\fR, \fB\-\-format=\fIFORMAT\fR
152 Use given archive \fBFORMAT\fR. Valid formats are (the number in
153 parentheses gives maximum size for individual archive member):
154 .RS
155 .TP
156 .B bin
157 The obsolete binary format. (2147483647 bytes)
158 .TP
159 .B odc
160 The old (POSIX.1) portable format. (8589934591 bytes)
161 .TP
162 .B newc
163 The new (SVR4) portable format, which supports file systems
164 having more than 65536 inodes. (4294967295 bytes)
165 .TP
166 .B crc
167 The new (SVR4) portable format with a checksum added.
168 .TP
169 .B tar
170 The old tar format. (8589934591 bytes)
171 .TP
172 .B ustar
173 The POSIX.1 tar format. Also recognizes GNU tar archives,
174 which are similar but not identical. (8589934591 bytes)
175 .TP
176 .B hpbin
177 The obsolete binary format used by HPUX's cpio (which stores
178 device files differently).
179 .TP
180 .B hpodc
181 The portable format used by HPUX's cpio (which stores device
182 files differently).
183 .RE
184 .TP
185 \fB\-R\fR, \fB\-\-owner=\fR[\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]
186 In copy-in and copy-pass mode, set the ownership of all files created
187 to the specified \fIUSER\fR and/or \fIGROUP\fR. In copy-out mode,
188 store the supplied owner information in the archive.
189
190 \fIUSER\fR and \fIGROUP\fR are first looked up in the system user and
191 group databases. If not found, \fBcpio\fR checks if they consist of
192 decimal digits only and, if so, treats them as numeric UID and GID,
193 correspondingly.
194
195 To avoid the lookup and ensure that arguments are treated as numeric
196 values, prefix them with a plus sign, e.g.: \fB-R +0:+0\fR.
197 .TP
198 .B \-\-quiet
199 Do not print the number of blocks copied at the end of the run.
200 .TP
201 .BI \-\-rsh\-command= COMMAND
202 Use remote \fICOMMAND\fR instead of \fBrsh\fR.
203 .TP
204 .BR \-v ", " \-\-verbose
205 Verbosely list the files processed.
206 .TP
207 .BR \-V ", " \-\-dot
208 Print a "\fB.\fR" for each file processed.
209 .TP
210 \fB\-W\fR, \fB\-\-warning=\fIFLAG\fR
211 Controls what warnings are displayed. The \fIFLAG\fR is one of
212 .BR none ,
213 to disable all warnings,
214 .B all
215 to enable them,
216 .BR truncate ,
217 to enable warnings about field truncation, and
218 .BR no\-truncate ,
219 to disable them.
220
221 Multiple \fB\-W\fR options accumulate.
222 .SS Operation modifiers valid in copy-in and copy-out modes
223 .TP
224 \fB\-F\fR, \fB\-\-file=\fR[[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE-FILE\fR
225 Use this \fIARCHIVE-FILE\fR instead of standard input (in copy-in
226 mode) or standard output (in copy-out mode). Optional \fIUSER\fR and
227 \fIHOST\fR specify the user and host names in case of a remote
228 archive.
229 .TP
230 \fB\-M\fR, \fB\-\-message=\fISTRING\fR
231 Print \fISTRING\fR when the end of a volume of the backup media is reached.
232 .SS Operation modifiers valid only in copy-in mode
233 .TP
234 .BR \-b ", " \-\-swap
235 Swap both halfwords of words and bytes of halfwords in the data.
236 Equivalent to \fB\-sS\fR.
237 .TP
238 .BR \-f ", " \-\-nonmatching
239 Only copy files that do not match any of the given patterns.
240 .TP
241 .BR \-n ", " \-\-numeric\-uid\-gid
242 In the verbose table of contents listing, show numeric UID and GID.
243 .\" FIXME: special meaning when storing tar files.
244 .TP
245 .BR \-r ", " \-\-rename
246 Interactively rename files.
247 .TP
248 .BR \-s ", " \-\-swap\-bytes
249 Swap the bytes of each halfword in the files.
250 .TP
251 .BR \-S ", " \-\-swap\-halfwords
252 Swap the halfwords of each word (4 bytes) in the files.
253 .TP
254 .BR \-t ", " \-\-list
255 Print a table of contents of the input. It can also be used alone, as a
256 mode designator, in which case \fB\-i\fR is implied.
257 .TP
258 .B \-\-to\-stdout
259 Extract files to standard output.
260 .TP
261 \fB\-E\fR, \fB\-\-pattern\-file=\fIFILE\fR
262 Read additional patterns specifying filenames to extract or list from
263 \fIFILE\fR.
264 .TP
265 .B \-\-only\-verify\-crc
266 When reading a CRC format archive, only verify the CRC's of each file
267 in the archive, without actually extracting the files.
268 .SS Operation modifiers valid only in copy-out mode
269 .TP
270 .BR \-A ", " \-\-append
271 Append to an existing archive.
272 .TP
273 .BR \-\-device\-independent ", " \-\-reproducible
274 Create reproducible archives. This is equivalent to
275 .BR "\-\-ignore\-devno \-\-ignore\-dirnlink \-\-renumber\-inodes" .
276 .TP
277 .B \-\-ignore\-devno
278 Store 0 in the device number field of each archive member, instead of
279 the actual device number.
280 .TP
281 .B \-\-ignore\-dirnlink
282 Store 2 in the
283 .I nlink
284 field of each directory archive member,
285 instead of the actual number of links.
286 .TP
287 \fB\-O\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE-NAME\fR
288 Use \fIARCHIVE-NAME\fR instead of standard output. Optional \fIUSER\fR and
289 \fIHOST\fR specify the user and host names in case of a remote
290 archive.
291
292 The output archive name can be specified either using this option, or
293 using \fB\-F\fR (\fB\-\-file\fR), but not both.
294 .TP
295 .B \-\-renumber\-inodes
296 Renumber inodes when storing them in the archive.
297 .SS Operation modifiers valid only in copy-pass mode
298 .TP
299 .BR \-l ", " \-\-link
300 Link files instead of copying them, when possible.
301 .SS Operation modifiers valid in copy-in and copy-out modes
302 .TP
303 .B \-\-absolute\-filenames
304 Do not strip file system prefix components from the file names. This
305 is the default.
306 .TP
307 .B \-\-no\-absolute\-filenames
308 Create all files relative to the current directory.
309 .SS Operation modifiers valid in copy-out and copy-pass modes
310 .TP
311 .BR \-0 ", " \-\-null
312 Filenames in the list are delimited by null characters instead of
313 newlines.
314 .TP
315 .BR \-a ", " \-\-reset\-access\-time
316 Reset the access times of files after reading them.
317 .TP
318 \fB\-I\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE-NAME\fR
319 Use \fIARCHIVE-NAME\fR instead of standard input. Optional \fIUSER\fR and
320 \fIHOST\fR specify the user and host names in case of a remote
321 archive.
322
323 The input archive name can be specified either using this option, or
324 using \fB\-F\fR (\fB\-\-file\fR), but not both.
325 .TP
326 .BR \-L ", " \-\-dereference
327 Dereference symbolic links (copy the files that they point to instead
328 of copying the links).
329 .SS Operation modifiers valid in copy-in and copy-pass modes
330 .TP
331 .BR \-d ", " \-\-make\-directories
332 Create leading directories where needed.
333 .TP
334 .BR \-m ", " \-\-preserve\-modification\-time
335 Retain previous file modification times when creating files.
336 .TP
337 .B \-\-no\-preserve\-owner
338 Do not change the ownership of the files.
339 .TP
340 .B \-\-sparse
341 Write files with large blocks of zeros as sparse files.
342 .TP
343 .BR \-u ", " \-\-unconditional
344 Replace all files unconditionally.
345 .SH "RETURN VALUE"
346 GNU \fBcpio\fR exits with code \fB0\fR if it was able to successfully
347 complete the requested operation. On errors, it exits with code \fB2\fR.
348 .SH "SEE ALSO"
349 .BR tar (1),
350 .BR rmt (8),
351 .BR mt (1).
352 .SH "BUG REPORTS"
353 Report bugs to <bug\[email protected]>.
354 .SH COPYRIGHT
355 Copyright \(co 2014\(en2025 Free Software Foundation, Inc.
356 .br
357 .na
358 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
359 .br
360 .ad
361 This is free software: you are free to change and redistribute it.
362 There is NO WARRANTY, to the extent permitted by law.
363 .\" Local variables:
364 .\" eval: (add-hook 'write-file-hooks 'time-stamp)
365 .\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
366 .\" time-stamp-format: "%:B %:d, %:y"
367 .\" time-stamp-end: "\""
368 .\" time-stamp-line-limit: 20
369 .\" end: