| blob | b1ba4724c765b62f79afa357a7642232b2c4045e |
1 .TH CPIO 1L \" -*- nroff -*-
2 .SH NAME
3 cpio \- copy files to and from archives
4 .SH SYNOPSIS
5 .B cpio
6 {\-o|\-\-create} [\-0acvABLV] [\-C bytes] [\-H format] [\-M message]
7 [\-O [[user@]host:]archive] [\-F [[user@]host:]archive]
8 [\-\-file=[[user@]host:]archive] [\-\-format=format] [\-\-message=message]
9 [\-\-null] [\-\-reset-access-time] [\-\-verbose] [\-\-dot] [\-\-append]
10 [\-\-block-size=blocks] [\-\-dereference] [\-\-io-size=bytes] [\-\-quiet]
11 [\-\-force\-local] [\-\-help] [\-\-version] < name-list [> archive]
13 .B cpio
14 {\-i|\-\-extract} [\-bcdfmnrtsuvBSV] [\-C bytes] [\-E file] [\-H format]
15 [\-M message] [\-R [user][:.][group]] [\-I [[user@]host:]archive]
16 [\-F [[user@]host:]archive] [\-\-file=[[user@]host:]archive]
17 [\-\-make-directories] [\-\-nonmatching] [\-\-preserve-modification-time]
18 [\-\-numeric-uid-gid] [\-\-rename] [\-\-list] [\-\-swap-bytes] [\-\-swap] [\-\-dot]
19 [\-\-unconditional] [\-\-verbose] [\-\-block-size=blocks] [\-\-swap-halfwords]
20 [\-\-io-size=bytes] [\-\-pattern-file=file] [\-\-format=format]
21 [\-\-owner=[user][:.][group]] [\-\-no-preserve-owner] [\-\-message=message]
22 [\-\-force\-local] [\-\-no\-absolute\-filenames] [\-\-sparse] [\-\-only\-verify\-crc]
23 [\-\-quiet] [\-\-help] [\-\-version] [pattern...] [< archive]
25 .B cpio
26 {\-p|\-\-pass-through} [\-0adlmuvLV] [\-R [user][:.][group]]
27 [\-\-null] [\-\-reset-access-time] [\-\-make-directories] [\-\-link] [\-\-quiet]
28 [\-\-preserve-modification-time] [\-\-unconditional] [\-\-verbose] [\-\-dot]
29 [\-\-dereference] [\-\-owner=[user][:.][group]] [\-\-no-preserve-owner]
30 [\-\-sparse] [\-\-help] [\-\-version] destination-directory < name-list
31 .SH DESCRIPTION
32 This manual page
33 documents the GNU version of
34 .BR cpio .
35 .B cpio
36 copies files into or out of a cpio or tar archive, which is a file that
37 contains other files plus information about them, such as their
38 file name, owner, timestamps, and access permissions. The archive can
39 be another file on the disk, a magnetic tape, or a pipe.
40 .B cpio
41 has three operating modes.
42 .PP
43 In copy-out mode,
44 .B cpio
45 copies files into an archive. It reads a list of filenames, one per
46 line, on the standard input, and writes the archive onto the standard
47 output. A typical way to generate the list of filenames is with the
48 .B find
49 command; you should give
50 .B find
51 the \-d option to minimize problems with permissions on
52 directories that are unwritable or not searchable.
53 .PP
54 In copy-in mode,
55 .B cpio
56 copies files out of an archive or lists the archive contents. It
57 reads the archive from the standard input. Any non-option command
58 line arguments are shell globbing patterns; only files in the archive
59 whose names match one or more of those patterns are copied from the
60 archive. Unlike in the shell, an initial `.' in a filename does
61 match a wildcard at the start of a pattern, and a `/' in a filename
62 can match wildcards. If no patterns are given, all files are
63 extracted.
64 .PP
65 In copy-pass mode,
66 .B cpio
67 copies files from one directory tree to another, combining the
68 copy-out and copy-in steps without actually using an archive.
69 It reads the list of files to copy from the standard input; the
70 directory into which it will copy them is given as a non-option
71 argument.
72 .PP
73 .B cpio
74 supports the following archive formats: binary, old ASCII, new
75 ASCII, crc, HPUX binary, HPUX old ASCII, old tar, and POSIX.1 tar.
76 The binary format
77 is obsolete because it encodes information about the files in a way
78 that is not portable between different machine architectures.
79 The old ASCII format is portable between different machine architectures,
80 but should not be used on file systems with more than 65536 i-nodes.
81 The new ASCII format is portable between different machine architectures
82 and can be used on any size file system, but is not supported by all
83 versions of
84 .BR cpio ;
85 currently, it is only supported by GNU and Unix System V R4.
86 The crc format is
87 like the new ASCII format, but also contains a checksum for each file
88 which
89 .B cpio
90 calculates when creating an archive
91 and verifies when the file is extracted from the archive.
92 The HPUX formats are provided for compatibility with HPUX's cpio which
93 stores device files differently.
94 .PP
95 The tar format is provided for compatibility with
96 the
97 .B tar
98 program. It can not be used to archive files with names
99 longer than 100 characters, and can not be used to archive "special"
100 (block or character devices) files.
101 The POSIX.1 tar format can not be used to archive files with names longer
102 than 255 characters (less unless they have a "/" in just the right place).
103 .PP
104 By default,
105 .B cpio
106 creates binary format archives, for compatibility with
107 older
108 .B cpio
109 programs.
110 When extracting from archives,
111 .B cpio
112 automatically recognizes which kind of archive it is reading and can
113 read archives created on machines with a different byte-order.
114 .PP
115 Some of the options to
116 .B cpio
117 apply only to certain operating modes; see the SYNOPSIS section for a
118 list of which options are allowed in which modes.
119 .SS OPTIONS
120 .TP
121 .I "\-0, \-\-null"
122 In copy-out and copy-pass modes, read a list of filenames terminated
123 by a null character instead of a newline, so that files whose names
124 contain newlines can be archived. GNU
125 .B find
126 is one way to produce a list of null-terminated filenames.
127 .TP
128 .I "\-a, \-\-reset-access-time"
129 Reset the access times of files after reading them, so that it does
130 not look like they have just been read.
131 .TP
132 .I "\-A, \-\-append"
133 Append to an existing archive. Only works in copy-out mode. The
134 archive must be a disk file specified with the
135 .I \-O
136 or
137 .I "\-F (\-\-file)"
138 option.
139 .TP
140 .I "\-b, \-\-swap"
141 In copy-in mode, swap both halfwords of words and bytes of halfwords
142 in the data. Equivalent to
143 .IR "\-sS" .
144 Use this option to convert 32-bit integers between big-endian and
145 little-endian machines.
146 .TP
147 .I "\-B"
148 Set the I/O block size to 5120 bytes. Initially the block size is 512
149 bytes.
150 .TP
151 .I "\-\-block-size=BLOCK-SIZE"
152 Set the I/O block size to BLOCK-SIZE * 512 bytes.
153 .TP
154 .I "\-c"
155 Use the old portable (ASCII) archive format.
156 .TP
157 .I "\-C IO-SIZE, \-\-io-size=IO-SIZE"
158 Set the I/O block size to IO-SIZE bytes.
159 .TP
160 .I "\-d, \-\-make-directories"
161 Create leading directories where needed.
162 .TP
163 .I "\-E FILE, \-\-pattern-file=FILE"
164 In copy-in mode, read additional patterns specifying filenames to
165 extract or list from FILE. The lines of FILE are treated as if they
166 had been non-option arguments to
167 .BR cpio .
168 .TP
169 .I "\-f, \-\-nonmatching"
170 Only copy files that do not match any of the given patterns.
171 .TP
172 .I "\-F, \-\-file=archive"
173 Archive filename to use instead of standard input or output. To use a
174 tape drive on another machine as the archive, use a filename that
175 starts with `HOSTNAME:'. The hostname can be preceded by a
176 username and an `@' to access the remote tape drive as that user, if
177 you have permission to do so (typically an entry in that user's
178 `~/.rhosts' file).
179 .TP
180 .I "\-\-force-local"
181 With
182 .IR \-F ,
183 .IR \-I ,
184 or
185 .IR \-O ,
186 take the archive file name to be a local file even if it contains a
187 colon, which would ordinarily indicate a remote host name.
188 .TP
189 .I "\-H FORMAT, \-\-format=FORMAT"
190 Use archive format FORMAT. The valid formats are listed below;
191 the same names are also recognized in all-caps. The default in
192 copy-in mode is to automatically detect the archive format, and in
193 copy-out mode is "bin".
194 .RS
195 .IP bin
196 The obsolete binary format.
197 .IP odc
198 The old (POSIX.1) portable format.
199 .IP newc
200 The new (SVR4) portable format, which supports file systems having
201 more than 65536 i-nodes.
202 .IP crc
203 The new (SVR4) portable format with a checksum added.
204 .IP tar
205 The old tar format.
206 .IP ustar
207 The POSIX.1 tar format. Also recognizes GNU
208 .B tar
209 archives, which are similar but not identical.
210 .IP hpbin
211 The obsolete binary format used by HPUX's cpio (which stores device files
212 differently).
213 .IP hpodc
214 The portable format used by HPUX's cpio (which stores device files differently).
215 .RE
216 .TP
217 .I "\-i, \-\-extract"
218 Run in copy-in mode.
219 .TP
220 .I "\-I archive"
221 Archive filename to use instead of standard input. To use a
222 tape drive on another machine as the archive, use a filename that
223 starts with `HOSTNAME:'. The hostname can be preceded by a
224 username and an `@' to access the remote tape drive as that user, if
225 you have permission to do so (typically an entry in that user's
226 `~/.rhosts' file).
227 .TP
228 .I \-k
229 Ignored; for compatibility with other versions of
230 .BR cpio .
231 .TP
232 .I "\-l, \-\-link"
233 Link files instead of copying them, when possible (usable only with the
234 .I \-p
235 option).
236 .TP
237 .I "\-L, \-\-dereference"
238 Dereference symbolic links (copy the files that they point to instead
239 of copying the links).
240 .TP
241 .I "\-m, \-\-preserve-modification-time"
242 Retain previous file modification times when creating files.
243 .TP
244 .I "\-M MESSAGE, \-\-message=MESSAGE"
245 Print MESSAGE when the end of a volume of the backup media (such as a
246 tape or a floppy disk) is reached, to prompt the user to insert a new
247 volume. If MESSAGE contains the string "%d", it is replaced by the
248 current volume number (starting at 1).
249 .TP
250 .I "\-n, \-\-numeric-uid-gid"
251 In the verbose table of contents listing, show numeric UID and GID
252 instead of translating them into names.
253 .TP
254 .I " \-\-no-absolute-filenames"
255 In copy-in mode, create all files relative to the current directory,
256 even if they have an absolute file name in the archive.
257 .TP
258 .I " \-\-no-preserve-owner"
259 In copy-in mode and copy-pass mode, do not change the ownership of the
260 files; leave them owned by the user extracting them. This is the
261 default for non-root users, so that users on System V don't
262 inadvertently give away files.
263 .TP
264 .I "\-o, \-\-create"
265 Run in copy-out mode.
266 .TP
267 .I "\-O archive"
268 Archive filename to use instead of standard output. To use a tape
269 drive on another machine as the archive, use a filename that starts
270 with `HOSTNAME:'. The hostname can be preceded by a username and an
271 `@' to access the remote tape drive as that user, if you have
272 permission to do so (typically an entry in that user's `~/.rhosts'
273 file).
274 .TP
275 .I " \-\-only-verify-crc"
276 When reading a CRC format archive in copy-in mode, only verify the
277 CRC's of each file in the archive, don't actually extract the files.
278 .TP
279 .I "\-p, \-\-pass-through"
280 Run in copy-pass mode.
281 .TP
282 .I "\-\-quiet"
283 Do not print the number of blocks copied.
284 .TP
285 .I "\-r, \-\-rename"
286 Interactively rename files.
287 .TP
288 .I "\-R [user][:.][group], \-\-owner [user][:.][group]"
289 In copy-out and copy-pass modes, set the ownership of all files created
290 to the specified user and/or group. Either the user or the group, or
291 both, must be present. If the group is omitted but the ":" or "."
292 separator is given, use the given user's login group. Only the
293 super-user can change files' ownership.
294 .TP
295 .I "\-\-sparse"
296 In copy-out and copy-pass modes, write files with large blocks of zeros
297 as sparse files.
298 .TP
299 .I "\-s, \-\-swap-bytes"
300 In copy-in mode, swap the bytes of each halfword (pair of bytes) in the
301 files.
302 .TP
303 .I "\-S, \-\-swap-halfwords"
304 In copy-in mode, swap the halfwords of each word (4 bytes) in the
305 files.
306 .TP
307 .I "\-t, \-\-list"
308 Print a table of contents of the input.
309 .TP
310 .I "\-u, \-\-unconditional"
311 Replace all files, without asking whether to replace existing newer
312 files with older files.
313 .TP
314 .I "\-v, \-\-verbose"
315 List the files processed, or with
316 .IR \-t ,
317 give an `ls \-l' style table of contents listing. In a verbose table
318 of contents of a ustar archive, user and group names in the archive
319 that do not exist on the local system are replaced by the names that
320 correspond locally to the numeric UID and GID stored in the archive.
321 .TP
322 .I "\-V \-\-dot"
323 Print a "." for each file processed.
324 .TP
325 .I "\-\-version"
326 Print the
327 .B cpio
328 program version number and exit.