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