1cpio(1) User Commands cpio(1)
2
6 cpio - copy file archives in and out
7
9 cpio -i [-bBcdfkmPrsStuvV6@/] [-C bufsize] [-E file]
10 [-H header] [-I [-M message]] [-R id] [pattern]...
11 cpio -o [-aABcLPvV@/] [-C bufsize] [-H header]
14 [-O file [-M message]]
15 cpio -p [-adlLmPuvV@/] [-R id] directory
18
21 The cpio command copies files into and out of a cpio archive. The cpio
22 archive can span multiple volumes. The -i, -o, and -p options select
23 the action to be performed. The following list describes each of the
24 actions. These actions are mutually exclusive.
25 Copy In Mode
27 cpio -i (copy in) extracts files from the standard input, which is
28 assumed to be the product of a previous cpio -o command. Only files
29 with names that match one of the patterns are selected. See sh(1) and
30 OPERANDS for more information about pattern. Extracted files are condi‐
31 tionally copied into the current directory tree, based on the options
32 described below. The permissions of the files are those of the previous
33 cpio -o command. The owner and group are the same as the current user,
34 unless the current user has the {PRIV_FILE_CHOWN_SELF} privilege. See
35 chown(2). If this is the case, owner and group are the same as those
36 resulting from the previous cpio -o command. Notice that if cpio -i
37 tries to create a file that already exists and the existing file is the
38 same age or younger (newer), cpio outputs a warning message and not
39 replace the file. The -u option can be used to unconditionally over‐
40 write the existing file.
41 Copy Out Mode
43 cpio -o (copy out) reads a list of file path names from the standard
44 input and copies those files to the standard output, together with path
45 name and status information in the form of a cpio archive. Output is
46 padded to an 8192-byte boundary by default or to the user-specified
47 block size (with the -B or -C options) or to some device-dependent
48 block size where necessary (as with the CTC tape).
49 Pass Mode
51 cpio -p (pass) reads a list of file path names from the standard input
52 and conditionally copies those files into the destination directory
53 tree, based on the options described below.
54 If the underlying file system of the source file supports detection of
57 holes as reported by pathconf(2), the file is a sparse file, and the
58 destination file is seekable, then holes in sparse files are preserved
59 in pass mode, otherwise holes are filled with zeros.
60 cpio assumes four-byte words.
63 If, when writing to a character device (-o) or reading from a character
66 device (-i), cpio reaches the end of a medium (such as the end of a
67 diskette), and the -O and -I options are not used, cpio prints the fol‐
68 lowing message:
69 To continue, type device/file name when ready.
71 To continue, you must replace the medium and type the character special
76 device name (/dev/rdiskette for example) and press RETURN. You might
77 want to continue by directing cpio to use a different device. For exam‐
78 ple, if you have two floppy drives you might want to switch between
79 them so cpio can proceed while you are changing the floppies. Press
80 RETURN to cause the cpio process to exit.
81
83 The following options are supported:
84 -i (copy in) Reads an archive from the standard input and condition‐
86 ally extracts the files contained in it and places them into the
87 current directory tree.
88 -o (copy out) Reads a list of file path names from the standard
91 input and copies those files to the standard output in the form
92 of a cpio archive.
93 -p (pass) Reads a list of file path names from the standard input
96 and conditionally copies those files into the destination direc‐
97 tory tree.
98 The following options can be appended in any sequence to the -i, -o, or
102 -p options:
103 -a Resets access times of input files after they have been
105 copied, making cpio's access invisible. Access times are
106 not reset for linked files when cpio -pla is specified.
107 -A Appends files to an archive. The -A option requires the
110 -O option. Valid only with archives that are files, or
111 that are on floppy diskettes or hard disk partitions. The
112 effect on files that are linked in the existing portion
113 of the archive is unpredictable.
114 -b Reverses the order of the bytes within each word. Use
117 only with the -i option.
118 -B Blocks input/output 5120 bytes to the record. The default
121 buffer size is 8192 bytes when this and the -C options
122 are not used. -B does not apply to the -p (pass) option.
123 -c Reads or writes header information in ASCII character
126 form for portability. There are no UID or GID restric‐
127 tions associated with this header format. Use this option
128 between SVR4-based machines, or the -H odc option between
129 unknown machines. The -c option implies the use of
130 expanded device numbers, which are only supported on
131 SVR4-based systems. When transferring files between SunOS
132 4 or Interactive UNIX and the Solaris 2.6 Operating envi‐
133 ronment or compatible versions, use -H odc.
134 -C bufsize Blocks input/output bufsize bytes to the record, where
137 bufsize is replaced by a positive integer. The default
138 buffer size is 8192 bytes when this and -B options are
139 not used. -C does not apply to the -p (pass) option.
140 -d Creates directories as needed.
143 -E file Specifies an input file (file) that contains a list of
146 filenames to be extracted from the archive (one filename
147 per line).
148 -f Copies in all files except those in patterns. See OPER‐
151 ANDS for a description of pattern.
152 -H header Reads or writes header information in header format.
155 Always use this option or the -c option when the origin
156 and the destination machines are different types. This
157 option is mutually exclusive with options -c and -6.
158 Valid values for header are:
160 bar bar head and format. Used only with the
162 -i option ( read only).
163 crc | CRC ASCII header with expanded device num‐
166 bers and an additional per-file check‐
167 sum. There are no UID or GID restric‐
168 tions associated with this header for‐
169 mat.
170 odc ASCII header with small device numbers.
173 This is the IEEE/P1003 Data Interchange
174 Standard cpio header and format. It has
175 the widest range of portability of any
176 of the header formats. It is the offi‐
177 cial format for transferring files
178 between POSIX-conforming systems (see
179 standards(5)). Use this format to commu‐
180 nicate with SunOS 4 and Interactive
181 UNIX. This header format allows UIDs and
182 GIDs up to 262143 to be stored in the
183 header.
184 tar | TAR tar header and format. This is an older
187 tar header format that allows UIDs and
188 GIDs up to 2097151 to be stored in the
189 header. It is provided for the reading
190 of legacy archives only, that is, in
191 conjunction with option -i.
192 Specifying this archive format with
194 option -o has the same effect as speci‐
195 fying the "ustar" format: the output ar‐
196 chive is in ustar format, and must be
197 read using -H ustar.
198 ustar | USTAR IEEE/P1003 Data Interchange Standard tar
201 header and format. This header format
202 allows UIDs and GIDs up to 2097151 to be
203 stored in the header.
204 Files with UIDs and GIDs greater than the limit stated
206 above are archived with the UID and GID of 60001. To
207 transfer a large file (8 Gb — 1 byte), the header format
208 can be tar|TAR, ustar|USTAR, or odc only.
209 -I file Reads the contents of file as an input archive, instead
212 of the standard input. If file is a character special
213 device, and the current medium has been completely read,
214 replace the medium and press RETURN to continue to the
215 next medium. This option is used only with the -i option.
216 -k Attempts to skip corrupted file headers and I/O errors
219 that might be encountered. If you want to copy files from
220 a medium that is corrupted or out of sequence, this
221 option lets you read only those files with good headers.
222 For cpio archives that contain other cpio archives, if an
223 error is encountered, cpio can terminate prematurely.
224 cpio finds the next good header, which can be one for a
225 smaller archive, and terminate when the smaller archive's
226 trailer is encountered. Use only with the -i option.
227 -l In pass mode, makes hard links between the source and
230 destination whenever possible. If the -L option is also
231 specified, the hard link is to the file referred to by
232 the symbolic link. Otherwise, the hard link is to the
233 symbolic link itself. Use only with the -p option.
234 -L Follows symbolic links. If a symbolic link to a directory
237 is encountered, archives the directory referred to by the
238 link, using the name of the link. Otherwise, archives the
239 file referred to by the link, using the name of the link.
240 -m Retains previous file modification time. This option is
243 ineffective on directories that are being copied.
244 -M message Defines a message to use when switching media. When you
247 use the -O or -I options and specify a character special
248 device, you can use this option to define the message
249 that is printed when you reach the end of the medium. One
250 %d can be placed in message to print the sequence number
251 of the next medium needed to continue.
252 -O file Directs the output of cpio to file, instead of the stan‐
255 dard output. If file is a character special device and
256 the current medium is full, replace the medium and type a
257 carriage return to continue to the next medium. Use only
258 with the -o option.
259 -P Preserves ACLs. If the option is used for output, exist‐
262 ing ACLs are written along with other attributes, except
263 for extended attributes, to the standard output. ACLs are
264 created as special files with a special file type. If the
265 option is used for input, existing ACLs are extracted
266 along with other attributes from standard input. The
267 option recognizes the special file type. Notice that
268 errors occurs if a cpio archive with ACLs is extracted by
269 previous versions of cpio. This option should not be used
270 with the -c option, as ACL support might not be present
271 on all systems, and hence is not portable. Use ASCII
272 headers for portability.
273 -r Interactively renames files. If the user types a carriage
276 return alone, the file is skipped. If the user types a
277 ``.'', the original pathname is retained. Not available
278 with cpio -p.
279 -R id Reassigns ownership and group information for each file
282 to user ID. (ID must be a valid login ID from the passwd
283 database.) This option is valid only when id is the
284 invoking user or the super-user. See NOTES.
285 -s Swaps bytes within each half word.
288 -S Swaps halfwords within each word.
291 -t Prints a table of contents of the input. If any file in
294 the table of contents has extended attributes, these are
295 also listed. No files are created. -t and -V are mutually
296 exclusive.
297 -u Copies unconditionally. Normally, an older file is not
300 replaced a newer file with the same name, although an
301 older directory updates a newer directory.
302 -v Verbose. Prints a list of file and extended attribute
305 names. When used with the -t option, the table of con‐
306 tents looks like the output of an ls -l command (see
307 ls(1)).
308 -V Special verbose. Prints a dot for each file read or writ‐
311 ten. Useful to assure the user that cpio is working with‐
312 out printing out all file names.
313 -6 Processes a UNIX System Sixth Edition archive format
316 file. Use only with the -i option. This option is mutu‐
317 ally exclusive with -c and -H.
318 -@ Includes extended attributes in archive. By default, cpio
321 does not place extended attributes in the archive. With
322 this flag, cpio looks for extended attributes on the
323 files to be placed in the archive and add them, as regu‐
324 lar files, to the archive. The extended attribute files
325 go in the archive as special files with special file
326 types. When the -@ flag is used with -i or -p, it
327 instructs cpio to restore extended attribute data along
328 with the normal file data. Extended attribute files can
329 only be extracted from an archive as part of a normal
330 file extract. Attempts to explicitly extract attribute
331 records are ignored.
332 -/ Includes extended system attributes in archive. By
335 default, cpio does not place extended system attributes
336 in the archive. With this flag, cpio looks for extended
337 system attributes on the files to be placed in the ar‐
338 chive and add them, as regular files, to the archive. The
339 extended attribute files go in the archive as special
340 files with special file types. When the -/ flag is used
341 with -i or -p, it instructs cpio to restore extended sys‐
342 tem attribute data along with the normal file data.
343 Extended system attribute files can only be extracted
344 from an archive as part of a normal file extract.
345 Attempts to explicitly extract attribute records are
346 ignored.
347
350 The following operands are supported:
351 directory A path name of an existing directory to be used as the
353 target of cpio -p.
354 pattern Expressions making use of a pattern-matching notation sim‐
357 ilar to that used by the shell (see sh(1)) for filename
358 pattern matching, and similar to regular expressions. The
359 following metacharacters are defined:
360 * Matches any string, including the empty string.
362 ? Matches any single character.
365 [...] Matches any one of the enclosed characters. A
368 pair of characters separated by `−' matches any
369 symbol between the pair (inclusive), as defined
370 by the system default collating sequence. If the
371 first character following the opening `[' is a
372 `!', the results are unspecified.
373 ! The ! (exclamation point) means not. For example,
376 the !abc* pattern would exclude all files that
377 begin with abc.
378 In pattern, metacharacters ?, *, and [...] match the slash
380 (/) character, and backslash (\) is an escape character.
381 Multiple cases of pattern can be specified and if no pat‐
382 tern is specified, the default for pattern is * (that is,
383 select all files).
384 Each pattern must be enclosed in double quotes. Otherwise,
386 the name of a file in the current directory might be used.
387
390 See largefile(5) for the description of the behavior of cpio when
391 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
392
394 The following examples show three uses of cpio.
395 Example 1 Using standard input
397 example% ls | cpio -oc > ../newfile
399 When standard input is directed through a pipe to cpio -o, as in the
404 example above, it groups the files so they can be directed (>) to a
405 single file (../newfile). The -c option insures that the file is porta‐
406 ble to other machines (as would the -H option). Instead of ls(1), you
407 could use find(1), echo(1), cat(1), and so on, to pipe a list of names
408 to cpio. You could direct the output to a device instead of a file.
409 Example 2 Extracting files into directories
412 example% cat newfile | cpio -icd "memo/a1" "memo/b*"
414 In this example, cpio -i uses the output file of cpio -o (directed
419 through a pipe with cat), extracts those files that match the patterns
420 (memo/a1, memo/b*), creates directories below the current directory as
421 needed (-d option), and places the files in the appropriate directo‐
422 ries. The -c option is used if the input file was created with a porta‐
423 ble header. If no patterns were given, all files from newfile would be
424 placed in the directory.
425 Example 3 Copying or linking files to another directory
428 example% find . -depth -print | cpio -pdlmv newdir
430 In this example, cpio -p takes the file names piped to it and copies or
435 links (-l option) those files to another directory, newdir. The -d
436 option says to create directories as needed. The -m option says to
437 retain the modification time. (It is important to use the -depth option
438 of find(1) to generate path names for cpio. This eliminates problems
439 that cpio could have trying to create files under read-only directo‐
440 ries.) The destination directory, newdir, must exist.
441 Notice that when you use cpio in conjunction with find, if you use the
445 -L option with cpio, you must use the -follow option with find and vice
446 versa. Otherwise, there are undesirable results.
447 For multi-reel archives, dismount the old volume, mount the new one,
450 and continue to the next tape by typing the name of the next device
451 (probably the same as the first reel). To stop, type a RETURN and cpio
452 ends.
453
455 See environ(5) for descriptions of the following environment variables
456 that affect the execution of cpio: LC_COLLATE, LC_CTYPE, LC_MESSAGES,
457 LC_TIME, TZ, and NLSPATH.
458 TMPDIR cpio creates its temporary file in /var/tmp by default. Oth‐
460 erwise, it uses the directory specified by TMPDIR.
461
464 The following exit values are returned:
465 0 Successful completion.
467 >0 An error occurred.
470
473 See attributes(5) for descriptions of the following attributes:
474 ┌─────────────────────────────┬─────────────────────────────┐
479 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
480 ├─────────────────────────────┼─────────────────────────────┤
481 │Availability │SUNWcsu │
482 ├─────────────────────────────┼─────────────────────────────┤
483 │CSI │Enabled │
484 ├─────────────────────────────┼─────────────────────────────┤
485 │Interface Stability │Committed │
486 └─────────────────────────────┴─────────────────────────────┘
487
489 ar(1), cat(1), echo(1), find(1), ls(1), pax(1), setfacl(1), sh(1),
490 tar(1), chown(2), archives.h(3HEAD), attributes(5), environ(5),
491 fsattr(5), largefile(5), standards(5)
492
494 The maximum path name length allowed in a cpio archive is determined by
495 the header type involved. The following table shows the proper value
496 for each supported archive header type.
497 Header type Command line options Maximum path name length
502 BINARY "-o" 256
503 POSIX "-oH odc" 256
504 ASCII "-oc" 1023
505 CRC "-oH crc" 1023
506 USTAR "-oH ustar" 255
507 When the command line options "-o -H tar" are specified, the archive
511 created is of type USTAR. This means that it is an error to read this
512 same archive using the command line options "-i -H tar". The archive
513 should be read using the command line options "-i -H ustar". The
514 options "-i -H tar" refer to an older tar archive format.
515 An error message is output for files whose UID or GID are too large to
518 fit in the selected header format. Use -H crc or -c to create archives
519 that allow all UID or GID values.
520 Only the super-user can copy special files.
523 Blocks are reported in 512-byte quantities.
526 If a file has 000 permissions, contains more than 0 characters of data,
529 and the user is not root, the file is not saved or restored.
530 When cpio is invoked in Copy In or Pass Mode by a user with
533 {PRIV_FILE_CHOWN_SELF} privilege, and in particular on a system where
534 {_POSIX_CHOWN_RESTRICTED} is not in effect (effectively granting this
535 privilege to all users where not overridden), extracted or copied files
536 can end up with owners and groups determined by those of the original
537 archived files, which can differ from the invoking user's. This might
538 not be what the user intended. The -R option can be used to retain file
539 ownership, if desired, if you specify the user's id.
540 The inode number stored in the header (/usr/include/archives.h) is an
543 unsigned short, which is 2 bytes. This limits the range of inode num‐
544 bers from 0 to 65535. Files which are hard linked must fall in this
545 inode range. This could be a problem when moving cpio archives between
546 different vendors' machines.
547 You must use the same blocking factor when you retrieve or copy files
550 from the tape to the hard disk as you did when you copied files from
551 the hard disk to the tape. Therefore, you must specify the -B or -C
552 option.
553 During -p and -o processing, cpio buffers the file list presented on
556 stdin in a temporary file.
557 The new pax(1) format, with a command that supports it (for example,
560 tar), should be used for large files. The cpio command is no longer
561 part of the current POSIX standard and is deprecated in favor of pax.
562SunOS 5.11 3 Aug 2009 cpio(1)