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