1 '\" te
2 .\" Copyright 1989 AT&T
3 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
4 .\" Copyright (c) 2012 Gary Mills
5 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
6 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/.
7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text
8 .\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical
9 .\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
10 .\" This notice shall appear on any product containing this material.
11 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
12 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
13 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
14 .TH CPIO 1 "Aug 3, 2009"
15 .SH NAME
16 cpio \- copy file archives in and out
17 .SH SYNOPSIS
18 .LP
19 .nf
20 \fBcpio\fR \fB-i\fR [\fB-bBcdfkmPqrsStuvV6@/\fR] [\fB-C\fR \fIbufsize\fR] [\fB-E\fR \fIfile\fR]
21 [\fB-H\fR \fIheader\fR] [\fB-I\fR \fI\fR [\fB-M\fR \fImessage\fR]] [\fB-R\fR \fIid\fR] [\fIpattern\fR]...
22 .fi
23
24 .LP
25 .nf
26 \fBcpio\fR \fB-o\fR [\fB-aABcLPqvV@/\fR] [\fB-C\fR \fIbufsize\fR] [\fB-H\fR \fIheader\fR]
27 [\fB-O\fR \fIfile\fR [\fB-M\fR \fImessage\fR]]
28 .fi
29
30 .LP
31 .nf
32 \fBcpio\fR \fB-p\fR [\fB-adlLmPquvV@/\fR] [\fB-R\fR \fIid\fR] \fIdirectory\fR
33 .fi
34
35 .SH DESCRIPTION
36 .sp
37 .LP
38 The \fBcpio\fR command copies files into and out of a \fBcpio\fR archive. The
39 \fBcpio\fR archive can span multiple volumes. The \fB-i\fR, \fB-o\fR, and
40 \fB-p\fR options select the action to be performed. The following list
41 describes each of the actions. These actions are mutually exclusive.
42 .SS "Copy In Mode"
43 .sp
44 .LP
45 \fBcpio\fR \fB-i\fR (copy in) extracts files from the standard input, which is
46 assumed to be the product of a previous \fBcpio\fR \fB-o\fR command. Only files
47 with names that match one of the \fIpattern\fRs are selected. See \fBsh\fR(1)
48 and OPERANDS for more information about \fIpattern\fR. Extracted files are
49 conditionally copied into the current directory tree, based on the options
50 described below. The permissions of the files are those of the previous \fBcpio
51 -o\fR command. The owner and group are the same as the current user, unless the
52 current user has the \fB{PRIV_FILE_CHOWN_SELF}\fR privilege. See
53 \fBchown\fR(2). If this is the case, owner and group are the same as those
54 resulting from the previous \fBcpio -o\fR command. Notice that if \fBcpio\fR
55 \fB-i\fR tries to create a file that already exists and the existing file is
56 the same age or younger (\fBnewer\fR), \fBcpio\fR outputs a warning message and
57 not replace the file. The \fB-u\fR option can be used to unconditionally
58 overwrite the existing file.
59 .SS "Copy Out Mode"
60 .sp
61 .LP
62 \fBcpio\fR \fB-o\fR (copy out) reads a list of file path names from the
63 standard input and copies those files to the standard output, together with
64 path name and status information in the form of a \fBcpio\fR archive. Output is
65 padded to an 8192-byte boundary by default or to the user-specified block size
66 (with the \fB-B\fR or \fB-C\fR options) or to some device-dependent block size
67 where necessary (as with the CTC tape).
68 .SS "Pass Mode"
69 .sp
70 .LP
71 \fBcpio\fR \fB-p\fR (pass) reads a list of file path names from the standard
72 input and conditionally copies those files into the destination directory tree,
73 based on the options described below.
74 .sp
75 .LP
76 If the underlying file system of the source file supports detection of holes as
77 reported by \fBpathconf\fR(2), the file is a sparse file, and the destination
78 file is seekable, then holes in sparse files are preserved in pass mode,
79 otherwise holes are filled with zeros.
80 .sp
81 .LP
82 \fBcpio\fR assumes four-byte words.
83 .sp
84 .LP
85 If, when writing to a character device (\fB-o\fR) or reading from a character
86 device (\fB-i\fR), \fBcpio\fR reaches the end of a medium (such as the end of a
87 diskette), and the \fB-O\fR and \fB-I\fR options are not used, \fBcpio\fR
88 prints the following message:
89 .sp
90 .in +2
91 .nf
92 To continue, type device/file name when ready.
93 .fi
94 .in -2
95 .sp
96
97 .sp
98 .LP
99 To continue, you must replace the medium and type the character special device
100 name (\fB/dev/rdiskette\fR for example) and press RETURN. You might want to
101 continue by directing \fBcpio\fR to use a different device. For example, if you
102 have two floppy drives you might want to switch between them so \fBcpio\fR can
103 proceed while you are changing the floppies. Press RETURN to cause the
104 \fBcpio\fR process to exit.
105 .SH OPTIONS
106 .sp
107 .LP
108 The following options are supported:
109 .sp
110 .ne 2
111 .na
112 \fB\fB-i\fR\fR
113 .ad
114 .RS 6n
115 (copy in) Reads an archive from the standard input and conditionally extracts
116 the files contained in it and places them into the current directory tree.
117 .RE
118
119 .sp
120 .ne 2
121 .na
122 \fB\fB-o\fR\fR
123 .ad
124 .RS 6n
125 (copy out) Reads a list of file path names from the standard input and copies
126 those files to the standard output in the form of a \fBcpio\fR archive.
127 .RE
128
129 .sp
130 .ne 2
131 .na
132 \fB\fB-p\fR\fR
133 .ad
134 .RS 6n
135 (pass) Reads a list of file path names from the standard input and
136 conditionally copies those files into the destination directory tree.
137 .RE
138
139 .sp
140 .LP
141 The following options can be appended in any sequence to the \fB-i\fR,
142 \fB-o\fR, or \fB-p\fR options:
143 .sp
144 .ne 2
145 .na
146 \fB\fB-a\fR\fR
147 .ad
148 .RS 14n
149 Resets access times of input files after they have been copied, making
150 \fBcpio\fR's access invisible. Access times are not reset for linked files when
151 \fBcpio\fR \fB-pla\fR is specified.
152 .RE
153
154 .sp
155 .ne 2
156 .na
157 \fB\fB-A\fR\fR
158 .ad
159 .RS 14n
160 Appends files to an archive. The \fB-A\fR option requires the \fB-O\fR option.
161 Valid only with archives that are files, or that are on floppy diskettes or
162 hard disk partitions. The effect on files that are linked in the existing
163 portion of the archive is unpredictable.
164 .RE
165
166 .sp
167 .ne 2
168 .na
169 \fB\fB-b\fR\fR
170 .ad
171 .RS 14n
172 Reverses the order of the bytes within each word. Use only with the \fB-i\fR
173 option.
174 .RE
175
176 .sp
177 .ne 2
178 .na
179 \fB\fB-B\fR\fR
180 .ad
181 .RS 14n
182 Blocks input/output 5120 bytes to the record. The default buffer size is 8192
183 bytes when this and the \fB-C\fR options are not used. \fB-B\fR does not apply
184 to the \fB-p\fR (pass) option.
185 .RE
186
187 .sp
188 .ne 2
189 .na
190 \fB\fB-c\fR\fR
191 .ad
192 .RS 14n
193 Reads or writes header information in \fBASCII\fR character form for
194 portability. There are no \fBUID\fR or \fBGID\fR restrictions associated with
195 this header format. Use this option between SVR4-based machines, or the
196 \fB-H\fR \fBodc\fR option between unknown machines. The \fB-c\fR option implies
197 the use of expanded device numbers, which are only supported on SVR4-based
198 systems. When transferring files between SunOS 4 or Interactive UNIX and the
199 Solaris 2.6 Operating environment or compatible versions, use \fB-H\fR
200 \fBodc\fR.
201 .RE
202
203 .sp
204 .ne 2
205 .na
206 \fB\fB-C\fR \fIbufsize\fR\fR
207 .ad
208 .RS 14n
209 Blocks input/output \fIbufsize\fR bytes to the record, where \fIbufsize\fR is
210 replaced by a positive integer. The default buffer size is 8192 bytes when this
211 and \fB-B\fR options are not used. \fB-C\fR does not apply to the \fB-p\fR
212 (pass) option.
213 .RE
214
215 .sp
216 .ne 2
217 .na
218 \fB\fB-d\fR\fR
219 .ad
220 .RS 14n
221 Creates directories as needed.
222 .RE
223
224 .sp
225 .ne 2
226 .na
227 \fB\fB-E\fR \fIfile\fR\fR
228 .ad
229 .RS 14n
230 Specifies an input file (\fIfile\fR) that contains a list of filenames to be
231 extracted from the archive (one filename per line).
232 .RE
233
234 .sp
235 .ne 2
236 .na
237 \fB\fB-f\fR\fR
238 .ad
239 .RS 14n
240 Copies in all files except those in \fIpattern\fRs. See OPERANDS for a
241 description of \fIpattern\fR.
242 .RE
243
244 .sp
245 .ne 2
246 .na
247 \fB\fB-H\fR \fIheader\fR\fR
248 .ad
249 .RS 14n
250 Reads or writes header information in \fIheader\fR format. Always use this
251 option or the \fB-c\fR option when the origin and the destination machines are
252 different types. This option is mutually exclusive with options \fB-c\fR and
253 \fB-6\fR.
254 .sp
255 Valid values for \fIheader\fR are:
256 .sp
257 .ne 2
258 .na
259 \fB\fBbar\fR\fR
260 .ad
261 .RS 17n
262 \fBbar\fR head and format. Used only with the \fB-i\fR option ( read only).
263 .RE
264
265 .sp
266 .ne 2
267 .na
268 \fB\fBcrc\fR | \fBCRC\fR\fR
269 .ad
270 .RS 17n
271 \fBASCII\fR header with expanded device numbers and an additional per-file
272 checksum. There are no \fBUID\fR or \fBGID\fR restrictions associated with this
273 header format.
274 .RE
275
276 .sp
277 .ne 2
278 .na
279 \fB\fBodc\fR\fR
280 .ad
281 .RS 17n
282 \fBASCII\fR header with small device numbers. This is the IEEE/P1003 Data
283 Interchange Standard cpio header and format. It has the widest range of
284 portability of any of the header formats. It is the official format for
285 transferring files between POSIX-conforming systems (see \fBstandards\fR(5)).
286 Use this format to communicate with SunOS 4 and Interactive UNIX. This header
287 format allows \fBUID\fRs and \fBGID\fRs up to 262143 to be stored in the
288 header.
289 .RE
290
291 .sp
292 .ne 2
293 .na
294 \fB\fBtar\fR | \fBTAR\fR\fR
295 .ad
296 .RS 17n
297 \fBtar\fR header and format. This is an older \fBtar\fR header format that
298 allows \fBUID\fRs and \fBGID\fRs up to 2097151 to be stored in the header. It
299 is provided for the reading of legacy archives only, that is, in conjunction
300 with option \fB-i\fR.
301 .sp
302 Specifying this archive format with option \fB-o\fR has the same effect as
303 specifying the "ustar" format: the output archive is in \fBustar\fR format, and
304 must be read using \fB-H\fR \fBustar\fR.
305 .RE
306
307 .sp
308 .ne 2
309 .na
310 \fB\fBustar\fR | \fBUSTAR\fR\fR
311 .ad
312 .RS 17n
313 IEEE/P1003 Data Interchange Standard tar header and format. This header format
314 allows \fBUID\fRs and \fBGID\fRs up to 2097151 to be stored in the header.
315 .RE
316
317 Files with \fBUID\fRs and \fBGID\fRs greater than the limit stated above are
318 archived with the \fBUID\fR and \fBGID\fR of \fB60001\fR. To transfer a large
319 file (8 Gb \(em 1 byte), the header format can be \fBtar|TAR\fR,
320 \fBustar|USTAR\fR, or \fBodc\fR only.
321 .RE
322
323 .sp
324 .ne 2
325 .na
326 \fB\fB-I\fR \fIfile\fR\fR
327 .ad
328 .RS 14n
329 Reads the contents of \fIfile\fR as an input archive, instead of the standard
330 input. If \fIfile\fR is a character special device, and the current medium has
331 been completely read, replace the medium and press RETURN to continue to the
332 next medium. This option is used only with the \fB-i\fR option.
333 .RE
334
335 .sp
336 .ne 2
337 .na
338 \fB\fB-k\fR\fR
339 .ad
340 .RS 14n
341 Attempts to skip corrupted file headers and I/O errors that might be
342 encountered. If you want to copy files from a medium that is corrupted or out
343 of sequence, this option lets you read only those files with good headers. For
344 \fBcpio\fR archives that contain other \fBcpio\fR archives, if an error is
345 encountered, \fBcpio\fR can terminate prematurely. \fBcpio\fR finds the next
346 good header, which can be one for a smaller archive, and terminate when the
347 smaller archive's trailer is encountered. Use only with the \fB-i\fR option.
348 .RE
349
350 .sp
351 .ne 2
352 .na
353 \fB\fB-l\fR\fR
354 .ad
355 .RS 14n
356 In pass mode, makes hard links between the source and destination whenever
357 possible. If the \fB-L\fR option is also specified, the hard link is to the
358 file referred to by the symbolic link. Otherwise, the hard link is to the
359 symbolic link itself. Use only with the \fB-p\fR option.
360 .RE
361
362 .sp
363 .ne 2
364 .na
365 \fB\fB-L\fR\fR
366 .ad
367 .RS 14n
368 Follows symbolic links. If a symbolic link to a directory is encountered,
369 archives the directory referred to by the link, using the name of the link.
370 Otherwise, archives the file referred to by the link, using the name of the
371 link.
372 .RE
373
374 .sp
375 .ne 2
376 .na
377 \fB\fB-m\fR\fR
378 .ad
379 .RS 14n
380 Retains previous file modification time. This option is ineffective on
381 directories that are being copied.
382 .RE
383
384 .sp
385 .ne 2
386 .na
387 \fB\fB-M\fR \fImessage\fR\fR
388 .ad
389 .RS 14n
390 Defines a \fImessage\fR to use when switching media. When you use the \fB-O\fR
391 or \fB-I\fR options and specify a character special device, you can use this
392 option to define the message that is printed when you reach the end of the
393 medium. One \fB%d\fR can be placed in \fImessage\fR to print the sequence
394 number of the next medium needed to continue.
395 .RE
396
397 .sp
398 .ne 2
399 .na
400 \fB\fB-O\fR \fIfile\fR\fR
401 .ad
402 .RS 14n
403 Directs the output of \fBcpio\fR to \fIfile\fR, instead of the standard output.
404 If \fIfile\fR is a character special device and the current medium is full,
405 replace the medium and type a carriage return to continue to the next medium.
406 Use only with the \fB-o\fR option.
407 .RE
408
409 .sp
410 .ne 2
411 .na
412 \fB\fB-P\fR\fR
413 .ad
414 .RS 14n
415 Preserves \fBACL\fRs. If the option is used for output, existing \fBACL\fRs are
416 written along with other attributes, except for extended attributes, to the
417 standard output. \fBACL\fRs are created as special files with a special file
418 type. If the option is used for input, existing \fBACL\fRs are extracted along
419 with other attributes from standard input. The option recognizes the special
420 file type. Notice that errors occurs if a \fBcpio\fR archive with \fBACL\fRs is
421 extracted by previous versions of \fBcpio\fR. This option should not be used
422 with the \fB-c\fR option, as \fBACL\fR support might not be present on all
423 systems, and hence is not portable. Use \fBASCII\fR headers for portability.
424 .RE
425
426 .sp
427 .ne 2
428 .na
429 \fB\fB-q\fR\fR
430 .ad
431 .RS 14n
432 Quiet. Suppresses the number of blocks message that normally is printed
433 after the copy is completed.
434 .RE
435
436 .sp
437 .ne 2
438 .na
439 \fB\fB-r\fR\fR
440 .ad
441 .RS 14n
442 Interactively renames files. If the user types a carriage return alone, the
443 file is skipped. If the user types a ``.'', the original pathname is retained.
444 Not available with \fBcpio\fR \fB-p\fR.
445 .RE
446
447 .sp
448 .ne 2
449 .na
450 \fB\fB-R\fR \fIid\fR\fR
451 .ad
452 .RS 14n
453 Reassigns ownership and group information for each file to user ID. (ID must be
454 a valid login ID from the \fBpasswd\fR database.) This option is valid only
455 when id is the invoking user or the super-user. See \fBNOTES\fR.
456 .RE
457
458 .sp
459 .ne 2
460 .na
461 \fB\fB-s\fR\fR
462 .ad
463 .RS 14n
464 Swaps bytes within each half word.
465 .RE
466
467 .sp
468 .ne 2
469 .na
470 \fB\fB-S\fR\fR
471 .ad
472 .RS 14n
473 Swaps halfwords within each word.
474 .RE
475
476 .sp
477 .ne 2
478 .na
479 \fB\fB-t\fR\fR
480 .ad
481 .RS 14n
482 Prints a table of contents of the input. If any file in the table of contents
483 has extended attributes, these are also listed. No files are created. \fB-t\fR
484 and \fB-V\fR are mutually exclusive.
485 .RE
486
487 .sp
488 .ne 2
489 .na
490 \fB\fB-u\fR\fR
491 .ad
492 .RS 14n
493 Copies unconditionally. Normally, an older file is not replaced a newer file
494 with the same name, although an older directory updates a newer directory.
495 .RE
496
497 .sp
498 .ne 2
499 .na
500 \fB\fB-v\fR\fR
501 .ad
502 .RS 14n
503 Verbose. Prints a list of file and extended attribute names. When used with the
504 \fB-t\fR option, the table of contents looks like the output of an \fBls\fR
505 \fB-l\fR command (see \fBls\fR(1)).
506 .RE
507
508 .sp
509 .ne 2
510 .na
511 \fB\fB-V\fR\fR
512 .ad
513 .RS 14n
514 Special verbose. Prints a dot for each file read or written. Useful to assure
515 the user that \fBcpio\fR is working without printing out all file names.
516 .RE
517
518 .sp
519 .ne 2
520 .na
521 \fB\fB-6\fR\fR
522 .ad
523 .RS 14n
524 Processes a UNIX System Sixth Edition archive format file. Use only with the
525 \fB-i\fR option. This option is mutually exclusive with \fB-c\fR and \fB-H\fR.
526 .RE
527
528 .sp
529 .ne 2
530 .na
531 \fB\fB-@\fR\fR
532 .ad
533 .RS 14n
534 Includes extended attributes in archive. By default, \fBcpio\fR does not place
535 extended attributes in the archive. With this flag, \fBcpio\fR looks for
536 extended attributes on the files to be placed in the archive and add them, as
537 regular files, to the archive. The extended attribute files go in the archive
538 as special files with special file types. When the \fB-@\fR flag is used with
539 \fB-i\fR or \fB-p\fR, it instructs \fBcpio\fR to restore extended attribute
540 data along with the normal file data. Extended attribute files can only be
541 extracted from an archive as part of a normal file extract. Attempts to
542 explicitly extract attribute records are ignored.
543 .RE
544
545 .sp
546 .ne 2
547 .na
548 \fB\fB-/\fR\fR
549 .ad
550 .RS 14n
551 Includes extended system attributes in archive. By default, \fBcpio\fR does not
552 place extended system attributes in the archive. With this flag, \fBcpio\fR
553 looks for extended system attributes on the files to be placed in the archive
554 and add them, as regular files, to the archive. The extended attribute files go
555 in the archive as special files with special file types. When the \fB-/\fR flag
556 is used with \fB-i\fR or \fB-p\fR, it instructs \fBcpio\fR to restore extended
557 system attribute data along with the normal file data. Extended system
558 attribute files can only be extracted from an archive as part of a normal file
559 extract. Attempts to explicitly extract attribute records are ignored.
560 .RE
561
562 .SH OPERANDS
563 .sp
564 .LP
565 The following operands are supported:
566 .sp
567 .ne 2
568 .na
569 \fB\fIdirectory\fR\fR
570 .ad
571 .RS 13n
572 A path name of an existing directory to be used as the target of \fBcpio\fR
573 \fB-p\fR.
574 .RE
575
576 .sp
577 .ne 2
578 .na
579 \fB\fIpattern\fR\fR
580 .ad
581 .RS 13n
582 Expressions making use of a pattern-matching notation similar to that used by
583 the shell (see \fBsh\fR(1)) for filename pattern matching, and similar to
584 regular expressions. The following metacharacters are defined:
585 .sp
586 .ne 2
587 .na
588 \fB\fB*\fR\fR
589 .ad
590 .RS 9n
591 Matches any string, including the empty string.
592 .RE
593
594 .sp
595 .ne 2
596 .na
597 \fB\fB?\fR\fR
598 .ad
599 .RS 9n
600 Matches any single character.
601 .RE
602
603 .sp
604 .ne 2
605 .na
606 \fB\fB[...]\fR\fR
607 .ad
608 .RS 9n
609 Matches any one of the enclosed characters. A pair of characters separated by
610 `\(mi' matches any symbol between the pair (inclusive), as defined by the
611 system default collating sequence. If the first character following the opening
612 \fB`['\fR is a \fB`!'\fR, the results are unspecified.
613 .RE
614
615 .sp
616 .ne 2
617 .na
618 \fB\fB!\fR\fR
619 .ad
620 .RS 9n
621 The ! (exclamation point) means \fInot\fR. For example, the \fB!abc*\fR pattern
622 would exclude all files that begin with \fBabc\fR.
623 .RE
624
625 In \fIpattern\fR, metacharacters \fB?\fR, \fB*\fR, and \fB[\fR\|.\|.\|.\fB]\fR
626 match the slash (\fB/\fR) character, and backslash (\fB\e\fR) is an escape
627 character. Multiple cases of \fIpattern\fR can be specified and if no
628 \fIpattern\fR is specified, the default for \fIpattern\fR is \fB*\fR (that is,
629 select all files).
630 .sp
631 Each pattern must be enclosed in double quotes. Otherwise, the name of a file
632 in the current directory might be used.
633 .RE
634
635 .SH USAGE
636 .sp
637 .LP
638 See \fBlargefile\fR(5) for the description of the behavior of \fBcpio\fR when
639 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
640 .SH EXAMPLES
641 .sp
642 .LP
643 The following examples show three uses of \fBcpio\fR.
644 .LP
645 \fBExample 1 \fRUsing standard input
646 .sp
647 .in +2
648 .nf
649 example% \fBls | cpio -oc > ../newfile\fR
650 .fi
651 .in -2
652 .sp
653
654 .sp
655 .LP
656 When standard input is directed through a pipe to \fBcpio\fR \fB-o\fR, as in
657 the example above, it groups the files so they can be directed (>) to a single
658 file (\fB\&../newfile\fR). The \fB-c\fR option insures that the file is
659 portable to other machines (as would the \fB-H\fR option). Instead of
660 \fBls\fR(1), you could use \fBfind\fR(1), \fBecho\fR(1), \fBcat\fR(1), and so
661 on, to pipe a list of names to \fBcpio\fR. You could direct the output to a
662 device instead of a file.
663
664 .LP
665 \fBExample 2 \fRExtracting files into directories
666 .sp
667 .in +2
668 .nf
669 example% \fBcat newfile | cpio -icd "memo/a1" "memo/b*"\fR
670 .fi
671 .in -2
672 .sp
673
674 .sp
675 .LP
676 In this example, \fBcpio\fR \fB-i\fR uses the output file of \fBcpio\fR
677 \fB-o\fR (directed through a pipe with \fBcat\fR), extracts those files that
678 match the patterns (\fBmemo/a1\fR, \fBmemo/b*\fR), creates directories below
679 the current directory as needed (\fB-d\fR option), and places the files in the
680 appropriate directories. The \fB-c\fR option is used if the input file was
681 created with a portable header. If no patterns were given, all files from
682 \fBnewfile\fR would be placed in the directory.
683
684 .LP
685 \fBExample 3 \fRCopying or linking files to another directory
686 .sp
687 .in +2
688 .nf
689 example% \fBfind . -depth -print | cpio -pdlmv newdir\fR
690 .fi
691 .in -2
692 .sp
693
694 .sp
695 .LP
696 In this example, \fBcpio\fR \fB-p\fR takes the file names piped to it and
697 copies or links (\fB-l\fR option) those files to another directory,
698 \fBnewdir\fR. The \fB-d\fR option says to create directories as needed. The
699 \fB-m\fR option says to retain the modification time. (It is important to use
700 the \fB-depth\fR option of \fBfind\fR(1) to generate path names for \fBcpio\fR.
701 This eliminates problems that \fBcpio\fR could have trying to create files
702 under read-only directories.) The destination directory, \fBnewdir\fR, must
703 exist.
704
705 .sp
706 .LP
707 Notice that when you use \fBcpio\fR in conjunction with \fBfind\fR, if you use
708 the \fB-L\fR option with \fBcpio\fR, you must use the \fB-follow\fR option with
709 \fBfind\fR and vice versa. Otherwise, there are undesirable results.
710 .sp
711 .LP
712 For multi-reel archives, dismount the old volume, mount the new one, and
713 continue to the next tape by typing the name of the next device (probably the
714 same as the first reel). To stop, type a RETURN and \fBcpio\fR ends.
715 .SH ENVIRONMENT VARIABLES
716 .sp
717 .LP
718 See \fBenviron\fR(5) for descriptions of the following environment variables
719 that affect the execution of \fBcpio\fR: \fBLC_COLLATE\fR, \fBLC_CTYPE\fR,
720 \fBLC_MESSAGES\fR, \fBLC_TIME\fR, \fBTZ\fR, and \fBNLSPATH\fR.
721 .sp
722 .ne 2
723 .na
724 \fB\fBTMPDIR\fR\fR
725 .ad
726 .RS 10n
727 \fBcpio\fR creates its temporary file in \fB/var/tmp\fR by default. Otherwise,
728 it uses the directory specified by \fBTMPDIR\fR.
729 .RE
730
731 .SH EXIT STATUS
732 .sp
733 .LP
734 The following exit values are returned:
735 .sp
736 .ne 2
737 .na
738 \fB\fB0\fR\fR
739 .ad
740 .RS 6n
741 Successful completion.
742 .RE
743
744 .sp
745 .ne 2
746 .na
747 \fB\fB>0\fR\fR
748 .ad
749 .RS 6n
750 An error occurred.
751 .RE
752
753 .SH ATTRIBUTES
754 .sp
755 .LP
756 See \fBattributes\fR(5) for descriptions of the following attributes:
757 .sp
758
759 .sp
760 .TS
761 box;
762 c | c
763 l | l .
764 ATTRIBUTE TYPE ATTRIBUTE VALUE
765 _
766 CSI Enabled
767 _
768 Interface Stability Committed
769 .TE
770
771 .SH SEE ALSO
772 .sp
773 .LP
774 \fBar\fR(1), \fBcat\fR(1), \fBecho\fR(1), \fBfind\fR(1), \fBls\fR(1),
775 \fBpax\fR(1), \fBsetfacl\fR(1), \fBsh\fR(1), \fBtar\fR(1), \fBchown\fR(2),
776 \fBarchives.h\fR(3HEAD), \fBattributes\fR(5), \fBenviron\fR(5),
777 \fBfsattr\fR(5), \fBlargefile\fR(5), \fBstandards\fR(5)
778 .SH NOTES
779 .sp
780 .LP
781 The maximum path name length allowed in a \fBcpio\fR archive is determined by
782 the header type involved. The following table shows the proper value for each
783 supported archive header type.
784 .sp
785
786 .sp
787 .TS
788 c c c
789 l l l .
790 Header type Command line options Maximum path name length
791 BINARY "\fB-o\fR" 256
792 POSIX "\fB-oH\fR odc" 256
793 ASCII "\fB-oc\fR" 1023
794 CRC "\fB-oH\fR crc" 1023
795 USTAR "\fB-oH\fR ustar" 255
796 .TE
797
798 .sp
799 .LP
800 When the command line options "\fB-o\fR \fB-H\fR \fBtar\fR" are specified, the
801 archive created is of type \fBUSTAR\fR. This means that it is an error to read
802 this same archive using the command line options "\fB-i\fR \fB-H\fR \fBtar\fR".
803 The archive should be read using the command line options "\fB-i\fR \fB-H\fR
804 \fBustar\fR". The options "\fB-i\fR \fB-H\fR \fBtar\fR" refer to an older tar
805 archive format.
806 .sp
807 .LP
808 An error message is output for files whose \fBUID\fR or \fBGID\fR are too large
809 to fit in the selected header format. Use \fB-H\fR \fBcrc\fR or \fB-c\fR to
810 create archives that allow all \fBUID\fR or \fBGID\fR values.
811 .sp
812 .LP
813 Only the super-user can copy special files.
814 .sp
815 .LP
816 Blocks are reported in 512-byte quantities.
817 .sp
818 .LP
819 If a file has \fB000\fR permissions, contains more than 0 characters of data,
820 and the user is not root, the file is not saved or restored.
821 .sp
822 .LP
823 When cpio is invoked in \fBCopy In\fR or \fBPass Mode\fR by a user with
824 \fB{PRIV_FILE_CHOWN_SELF}\fR privilege, and in particular on a system where
825 \fB{_POSIX_CHOWN_RESTRICTED}\fR is not in effect (effectively granting this
826 privilege to all users where not overridden), extracted or copied files can end
827 up with owners and groups determined by those of the original archived files,
828 which can differ from the invoking user's. This might not be what the user
829 intended. The \fB-R\fR option can be used to retain file ownership, if desired,
830 if you specify the user's id.
831 .sp
832 .LP
833 The inode number stored in the header (\fB/usr/include/archives.h\fR) is an
834 unsigned short, which is 2 bytes. This limits the range of inode numbers from
835 \fB0\fR to \fB65535\fR. Files which are hard linked must fall in this inode
836 range. This could be a problem when moving \fBcpio\fR archives between
837 different vendors' machines.
838 .sp
839 .LP
840 You must use the same blocking factor when you retrieve or copy files from the
841 tape to the hard disk as you did when you copied files from the hard disk to
842 the tape. Therefore, you must specify the \fB-B\fR or \fB-C\fR option.
843 .sp
844 .LP
845 During \fB-p\fR and \fB-o\fR processing, \fBcpio\fR buffers the file list
846 presented on stdin in a temporary file.
847 .sp
848 .LP
849 The new \fBpax\fR(1) format, with a command that supports it (for example,
850 \fBtar\fR), should be used for large files. The \fBcpio\fR command is no longer
851 part of the current POSIX standard and is deprecated in favor of \fBpax\fR.