aboutsummaryrefslogtreecommitdiff
path: root/doc/cpio.1
blob: d48d2df448b60706b49541260bdfb3decdc4e595 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
.\" This file is part of GNU cpio. -*- nroff -*-
.\" Copyright 2014 Free Software Foundation, Inc.
.\"
.\" GNU cpio is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" GNU cpio is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with GNU cpio.  If not, see <http://www.gnu.org/licenses/>.
.TH CPIO 1 "January 30, 2014" "CPIO" "GNU CPIO"
.SH NAME
cpio \- copy files to and from archives
.SH SYNOPSIS
.B cpio
{\fB\-o\fR|\fB\-\-create\fR} [\fB\-0acvABLV\fR] [\fB\-C\fR \fIBYTES\fR]
[\fB\-H\fR \fIFORMAT\fR] [\fB\-M\fR \fIMESSAGE\fR]
[\fB\-O\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
[\fB\-F\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
[\fB\-\-file=\fR[[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
[\fB\-\-format=\fIFORMAT\fR] [\fB\-\-message=\fIMESSAGE\fR]
[\fB\-\-null\fR] [\fB\-\-reset\-access\-time\fR] [\fB\-\-verbose\fR]
[\fB\-\-dot\fR] [\fB\-\-append\fR]
[\fB\-\-block\-size=\fIblocks\fR] [\fB\-\-dereference\fR]
[\fB\-\-io\-size=\fIBYTES\fR] [\fB\-\-quiet\fR]
[\fB\-\-force\-local\fR] [\fB\-\-rsh\-command=\fICOMMAND\fR]
< \fIname-list\fR [\fB>\fR \fIarchive\fR]

.B cpio
{\fB\-i\fR|\fB\-\-extract\fR} [\fB\-bcdfmnrtsuvBSV\fR] [\fB\-C\fR \fIBYTES\fR]
[\fB\-E\fR \fIFILE\fR] [\fB\-H\fR \fIFORMAT\fR]
[\fB\-M\fR \fIMESSAGE\fR] [\fB\-R\fR [\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]]
[\fB\-I\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
[\fB\-F\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
[\fB\-\-file=\fR[[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
[\fB\-\-make\-directories\fR] [\fB\-\-nonmatching\fR]
[\fB\-\-preserve\-modification\-time\fR] [\fB\-\-numeric\-uid\-gid\fR]
[\fB\-\-rename\fR] [\fB\-\-list\fR] [\fB\-\-swap\-bytes\fR]
[\fB\-\-swap\fR] [\fB\-\-dot\fR] [\fB\-\-unconditional\fR]
[\fB\-\-verbose\fR] [\fB\-\-block\-size=\fIBLOCKS\fR]
[\fB\-\-swap\-halfwords\fR] [\fB\-\-io\-size=\fIBYTES\fR]
[\fB\-\-pattern\-file=\fIFILE\fR] [\fB\-\-format=\fIFORMAT\fR]
[\fB\-\-owner=\fR[\fIUSER][\fB:.\fR][\fIGROUP\fR]]
[\fB\-\-no\-preserve\-owner\fR] [\fB\-\-message=\fIMESSAGE\fR]
[\fB\-\-force\-local\fR] [\fB\-\-no\-absolute\-filenames\fR] [\fB\-\-sparse\fR]
[\fB\-\-only\-verify\-crc\fR] [\fB\-\-to\-stdout\fR] [\fB\-\-quiet\fR]
[\fB\-\-rsh\-command=\fICOMMAND\fR]
[\fIpattern\fR...] [\fB<\fR \fIarchive\fR]

.B cpio
{\fB\-p\fR|\fB\-\-pass\-through\fR} [\fB\-0adlmuvLV\fR]
[\fB\-R\fR [\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]]
[\fB\-\-null\fR] [\fB\-\-reset\-access\-time\fR]
[\fB\-\-make\-directories\fR] [\fB\-\-link\fR] [\fB\-\-quiet\fR]
[\fB\-\-preserve\-modification\-time] [\fB\-\-unconditional\fR]
[\fB\-\-verbose\fR] [\fB\-\-dot\fR] [\fB\-\-dereference\fR]
[\fB\-\-owner=\fR[\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]]
[\fB\-\-no\-preserve\-owner\fR] [\fB\-\-sparse\fR]
\fIdestination-directory\fR \fB<\fR \fIname-list\fR

.B cpio
{\fB\-?\fR|\fB\-\-help\fR|\fB\-\-usage\fR|\fB\-\-version\fR}
.SH NOTE
This manpage is a short description of GNU \fBcpio\fR.  For a detailed
discussion, including examples and usage recommendations, refer to the
\fBGNU Cpio Manual\fR available in texinfo format.  If the \fBinfo\fR
reader and the cpio documentation are properly installed on your
system, the command
.PP
.RS +4
.B info cpio
.RE
.PP
should give you access to the complete manual.
.PP
You can also view the manual using the info mode in
.BR emacs (1),
or find it in various formats online at
.PP
.RS +4
.B http://www.gnu.org/software/cpio/manual
.RE
.PP
If any discrepancies occur between this manpage and the
\fBGNU Cpio Manual\fR, the later shall be considered the authoritative
source.
.SH DESCRIPTION
GNU \fBcpio\fR copies files between archives and directories.  It
supports the following archive formats: old binary cpio, old portable
cpio, SVR4 cpio with and without checksum, HP cpio, and various tar
formats.
.PP
The operation mode is requested by one of the following options:
.TP
.BR \-o ", " \-\-create
Copy-out.  Read a list of file names from the standard input and
create on the standard output (unless overridden by the \fB\-\-file\fR
option) an archive containing these files.
.TP
.BR \-i ", " \-\-extract
Copy-in.  Read the archive from standard input (or from the file
supplied with the \fB\-\-file\fR option) and extract files from it, or
(if the \fB\-t\fR option is given) list its contents to the standard
output.  If one or more \fIpattern\fRs are supplied, read or list only
files matching these patterns.  The \fB\-t\fR option alone implies
\fB\-i\fR. 
.TP
.BR \-p ", " \-\-pass\-through
Pass-through.  Read a list of file names from the standard input and
copy them to the specified directory.
.TP
.BR \-? ", " \-\-help
Give a short help summary and exit.
.TP
.B \-\-usage
Print a short usage message and exit.
.TP
.B \-\-version
Print program version and exit.
.SH OPTIONS
.SS Operation modifiers valid in any mode
.TP
\fB\-\-block\-size=\FIBLOCK-SIZE\fR
Set the I/O block size to \fIBLOCK-SIZE\fR * 512 bytes.
.TP
.B \-B
Set the I/O block size to 5120 bytes.
.TP
.B \-c
Use the old portable (ASCII) archive format.  This is the same as
\fB\-H odc\fR.
.TP
\fB\-C\fR, \fB\-\-io\-size=\fINUMBER\fR
Set the I/O block size to the given \fINUMBER\fR of bytes.
.TP
\fB\-D\fR, \fB\-\-directory=\fIDIR\fR
Change to directory \fIDIR\fR.
.TP
.B \-\-force\-local
Archive file is local, even if its name contains colons.
.TP
\fB\-H\fR, \fB\-\-format=\fIFORMAT\fR
Use given archive \fBFORMAT\fR.  Valid formats are (the number in
parentheses gives maximum size for individual archive member):
.RS
.TP
.B bin
The obsolete binary format.  (2147483647 bytes)
.TP
.B odc
The old (POSIX.1) portable format. (8589934591 bytes)
.TP
.B newc
The new (SVR4) portable format, which supports file systems
having more than 65536 i-nodes. (4294967295 bytes)
.TP
.B crc
The new (SVR4) portable format with a checksum added.
.TP
.B tar
The old tar format. (8589934591 bytes)
.TP
.B ustar
The POSIX.1 tar format.  Also recognizes GNU tar archives,
which are similar but not identical. (8589934591 bytes)
.TP
.B hpbin
The obsolete binary format used by HPUX's cpio (which stores
device files differently).
.TP
.B hpodc
The portable format used by HPUX's cpio (which stores device
files differently).
.RE
.TP
\fB\-R\fR, \fB\-\-owner=\fR[\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]
In copy-in and copy-pass mode, set the ownership of all files created
to the specified \fIUSER\fR and/or \fIGROUP\fR.  In copy-out mode,
store the supplied owner information in the archive.

\fIUSER\fR and \fIGROUP\fR are first looked up in the system user and
group databases.  If not found, \fBcpio\fR checks if they consist of
decimal digits only and, if so, treats them as numeric UID and GID,
correspondingly.

To avoid the lookup and ensure that arguments are treated as numeric
values, prefix them with a plus sign, e.g.: \fB-R +0:+0\fR.
.TP
.B \-\-quiet
Do not print the number of blocks copied at the end of the run.
.TP
.BI \-\-rsh\-command= COMMAND
Use remote \fICOMMAND\fR instead of \fBrsh\fR.
.TP
.BR \-v ", " \-\-verbose
Verbosely list the files processed.
.TP
.BR \-V ", " \-\-dot
Print a "\fB.\fR" for each file processed.
.TP
\fB\-W\fR, \fB\-\-warning=\fIFLAG\fR
Controlsи warning display.  The \fIFLAG\fR is one of
.BR none ,
to disable all warnings,
.BR all
to enable them,
.BR truncate ,
to enable warnings about field truncation, and
.BR no\-truncate ,
to disable them.

Multiple \fB\-W\fR options accumulate.
.SS Operation modifiers valid in copy-in and copy-out modes
.TP
\fB\-F\fR, \fB\-\-file=\fR[[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE-FILE\fR
Use this \fIARCHIVE-FILE\fR instead of standard input (in copy-in
mode) or standard output (in copy-out mode).  Optional \fIUSER\fR and
\fIHOST\fR specify the user and host names in case of a remote
archive.
.TP
\fB\-M\fR, \fB\-\-message=\fISTRING\fR
Print \fISTRING\fR when the end of a volume of the backup media is reached.
.SS Operation modifiers valid only in copy-in mode
.TP
.BR \-b ", " \-\-swap
Swap both halfwords of words and bytes of halfwords in the data.
Equivalent to \fB\-sS\fR. 
.TP
.BR \-f ", " \-\-nonmatching
Only copy files that do not match any of the given patterns.
.TP
.BR \-n ", " \-\-numeric\-uid\-gid
In the verbose table of contents listing, show numeric UID and GID.
.\" FIXME: special meaning when storing tar files.
.TP
.BR \-r ", " \-\-rename
Interactively rename files.
.TP
.BR \-s ", " \-\-swap\-bytes
Swap the bytes of each halfword in the files.
.TP
.BR \-S ", " \-\-swap\-halfwords
Swap the halfwords of each word (4 bytes) in the files.
.TP
.B \-\-to\-stdout
Extract files to standard output.
.TP
\fB\-E\fR, \fB\-\-pattern\-file=\fIFILE\fR
Read additional patterns specifying filenames to extract or list from
\fIFILE\fR.
.TP
.B \-\-only\-verify\-crc
When reading a CRC format archive, only verify the CRC's of each file
in the archive, without actually extracting the files.
.SS Operation modifiers valid only in copy-out mode
.TP
.BR \-A ", " \-\-append
Append to an existing archive.
.TP
\fB\-O\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE-NAME\fR
Use \fIARCHIVE-NAME\fR instead of standard output. Optional \fIUSER\fR and
\fIHOST\fR specify the user and host names in case of a remote
archive.

The output archive name can be specified wither using this option, or
using \fB\-F\fR (\fB\-\-file\fR), but not both.
.SS Operation modifiers valid only in copy-pass mode
.TP
.BR \-l ", " \-\-link
Link files instead of copying them, when possible.
.SS Operation modifiers valid in copy-in and copy-out modes
.TP
.B \-\-absolute\-filenames
Do not strip file system prefix components from the file names.
.TP
.B \-\-no\-absolute\-filenames
Create all files relative to the current directory.
.SS Operation modifiers valid in copy-out and copy-pass modes
.TP
.BR \-0 ", " \-\-null
Filenames in the list are delimited by null characters instead of
newlines.
.TP
.BR \-a ", " \-\-reset\-access\-time
Reset the access times of files after reading them.
.TP                            
\fB\-I\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE-NAME\fR
Use \fIARCHIVE-NAME\fR instead of standard input. Optional \fIUSER\fR and
\fIHOST\fR specify the user and host names in case of a remote
archive.

The input archive name can be specified wither using this option, or
using \fB\-F\fR (\fB\-\-file\fR), but not both.
.TP
.BR \-L ", " \-\-dereference
Dereference symbolic links (copy the files that they point to instead
of copying the links).
.SS Operation modifiers valid in copy-in and copy-pass modes
.TP
.BR \-d ", " \-\-make\-directories
Create leading directories where needed.
.TP
.BR \-m ", " \-\-preserve\-modification\-time
Retain previous file modification times when creating files.
.TP
.B \-\-no\-preserve\-owner
Do not change the ownership of the files.
.TP
.B \-\-sparse
Write files with large blocks of zeros as sparse files.
.TP
.BR \-u ", " \-\-unconditional
Replace all files unconditionally.
.SH "RETURN VALUE"
GNU \fBcpio\fR exits with code \fB0\fR if it was able to successfully
complete the requested operation.  On errors, it exits with code \fB2\fR.
.SH "SEE ALSO"
.BR tar (1),
.BR rmt (8),
.BR mt (1).
.SH "BUG REPORTS"
Report bugs to <bug\-cpio@gnu.org>.
.SH COPYRIGHT
Copyright \(co 2014 Free Software Foundation, Inc.
.br
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end:

Return to:

Send suggestions and report system problems to the System administrator.