1 \input texinfo @c -*-texinfo-*-
6 @set VERSION GNU cpio 2.5
7 @set RELEASEDATE June 2002
13 * cpio: (cpio). Making tape (or disk) archives.
19 This file documents @value{VERSION}.
21 Copyright (C) 1995, 2001, 2002 Free Software Foundation, Inc.
23 Permission is granted to make and distribute verbatim copies of
24 this manual provided the copyright notice and this permission notice
25 are preserved on all copies.
28 Permission is granted to process this file through TeX and print the
29 results, provided the printed document carries copying permission
30 notice identical to this one except for the removal of this paragraph
34 Permission is granted to copy and distribute modified versions of this
35 manual under the conditions for verbatim copying, provided that the entire
36 resulting derived work is distributed under the terms of a permission
37 notice identical to this one.
39 Permission is granted to copy and distribute translations of this manual
40 into another language, under the above conditions for modified versions,
41 except that this permission notice may be stated in a translation approved
48 @subtitle @value{VERSION} @value{RELEASEDATE}
49 @author by Robert Carleton
52 @vskip 0pt plus 1filll
53 Copyright @copyright{} 1995, 2001, 2002 Free Software Foundation, Inc.
55 This is the first edition of the GNU cpio documentation,@*
56 and is consistent with @value{VERSION}.@*
58 Published by the Free Software Foundation @*
59 59 Temple Place - Suite 330, @*
60 Boston, MA 02111-1307, USA @*
62 Permission is granted to make and distribute verbatim copies of
63 this manual provided the copyright notice and this permission notice
64 are preserved on all copies.
66 Permission is granted to copy and distribute modified versions of this
67 manual under the conditions for verbatim copying, provided that the entire
68 resulting derived work is distributed under the terms of a permission
69 notice identical to this one.
71 Permission is granted to copy and distribute translations of this manual
72 into another language, under the above conditions for modified versions,
73 except that this permission notice may be stated in a translation
74 approved by the Free Software Foundation.
78 @node Top, Introduction, (dir), (dir)
79 @comment node-name, next, previous, up
82 GNU cpio is a tool for creating and extracting archives, or copying
83 files from one place to another. It handles a number of cpio formats as
84 well as reading and writing tar files. This is the first edition of the
85 GNU cpio documentation and is consistant with @value{VERSION}.
89 * Tutorial:: Getting started.
90 * Invoking `cpio':: How to invoke `cpio'.
91 * Media:: Using tapes and other archive media.
92 * Concept Index:: Concept index.
94 --- The Detailed Node Listing ---
106 @node Introduction, Tutorial, Top, Top
107 @comment node-name, next, previous, up
108 @chapter Introduction
110 GNU cpio copies files into or out of a cpio or tar archive, The archive
111 can be another file on the disk, a magnetic tape, or a pipe.
113 GNU cpio supports the following archive formats: binary, old ASCII, new
114 ASCII, crc, HPUX binary, HPUX old ASCII, old tar, and POSIX.1 tar. The
115 tar format is provided for compatability with the tar program. By
116 default, cpio creates binary format archives, for compatibility with
117 older cpio programs. When extracting from archives, cpio automatically
118 recognizes which kind of archive it is reading and can read archives
119 created on machines with a different byte-order.
121 @node Tutorial, Invoking `cpio', Introduction, Top
122 @comment node-name, next, previous, up
124 @cindex creating a cpio archive
125 @cindex extracting a cpio archive
126 @cindex copying directory structures
127 @cindex passing directory structures
130 GNU cpio performs three primary functions. Copying files to an
131 archive, Extracting files from an archive, and passing files to another
132 directory tree. An archive can be a file on disk, one or more floppy
133 disks, or one or more tapes.
135 When creating an archive, cpio takes the list of files to be processed
136 from the standard input, and then sends the archive to the standard
137 output, or to the device defined by the @samp{-F} option.
138 @xref{Copy-out mode}. Usually find or ls is used to provide this list
139 to the standard input. In the following example you can see the
140 possibilities for archiving the contents of a single directory.
145 % ls | cpio -ov > directory.cpio
149 The @samp{-o} option creates the archive, and the @samp{-v} option
150 prints the names of the files archived as they are added. Notice that
151 the options can be put together after a single @samp{-} or can be placed
152 separately on the command line. The @samp{>} redirects the cpio output
153 to the file @samp{directory.cpio}.
156 If you wanted to archive an entire directory tree, the find command can
157 provide the file list to cpio:
162 % find . -print -depth | cpio -ov > tree.cpio
167 This will take all the files in the current directory, the directories
168 below and place them in the archive tree.cpio. Again the @samp{-o}
169 creates an archive, and the @samp{-v} option shows you the name of the
170 files as they are archived. @xref{Copy-out mode}. Using the `.' in the
171 find statement will give you more flexibility when doing restores, as it
172 will save file names with a relative path vice a hard wired, absolute
173 path. The @samp{-depth} option forces @samp{find} to print of the
174 entries in a directory before printing the directory itself. This
175 limits the effects of restrictive directory permissions by printing the
176 directory entries in a directory before the directory name itself.
181 Extracting an archive requires a bit more thought because cpio will not
182 create directories by default. Another characteristic, is it will not
183 overwrite existing files unless you tell it to.
188 % cpio -iv < directory.cpio
192 This will retrieve the files archived in the file directory.cpio and
193 place them in the present directory. The @samp{-i} option extracts the
194 archive and the @samp{-v} shows the file names as they are extracted.
195 If you are dealing with an archived directory tree, you need to use the
196 @samp{-d} option to create directories as necessary, something like:
200 % cpio -idv < tree.cpio
204 This will take the contents of the archive tree.cpio and extract it to
205 the current directory. If you try to extract the files on top of files
206 of the same name that already exist (and have the same or later
207 modification time) cpio will not extract the file unless told to do so
208 by the -u option. @xref{Copy-in mode}.
211 In copy-pass mode, cpio copies files from one directory tree to another,
212 combining the copy-out and copy-in steps without actually using an
213 archive. It reads the list of files to copy from the standard input;
214 the directory into which it will copy them is given as a non-option
215 argument. @xref{Copy-pass mode}.
219 % find . -depth -print0 | cpio --null -pvd new-dir
224 The example shows copying the files of the present directory, and
225 sub-directories to a new directory called new-dir. Some new options are
226 the @samp{-print0} available with GNU find, combined with the
227 @samp{--null} option of cpio. These two options act together to send
228 file names between find and cpio, even if special characters are
229 embedded in the file names. Another is @samp{-p}, which tells cpio to
230 pass the files it finds to the directory @samp{new-dir}.
232 @node Invoking `cpio', Media, Tutorial, Top
233 @comment node-name, next, previous, up
234 @chapter Invoking cpio
235 @cindex invoking cpio
236 @cindex command line options
245 @node Copy-out mode, Copy-in mode, Invoking `cpio', Invoking `cpio'
246 @comment node-name, next, previous, up
247 @section Copy-out mode
249 In copy-out mode, cpio copies files into an archive. It reads a list
250 of filenames, one per line, on the standard input, and writes the
251 archive onto the standard output. A typical way to generate the list
252 of filenames is with the find command; you should give find the -depth
253 option to minimize problems with permissions on directories that are
258 cpio @{-o|--create@} [-0acvABLV] [-C bytes] [-H format]
259 [-M message] [-O [[user@@]host:]archive] [-F [[user@@]host:]archive]
260 [--file=[[user@@]host:]archive] [--format=format]
261 [--message=message][--null] [--reset-access-time] [--verbose]
262 [--dot] [--append] [--block-size=blocks] [--dereference]
263 [--io-size=bytes] [--rsh-command=command] [--help] [--version]
264 < name-list [> archive]
267 @node Copy-in mode, Copy-pass mode, Copy-out mode, Invoking `cpio'
268 @comment node-name, next, previous, up
269 @section Copy-in mode
271 In copy-in mode, cpio copies files out of an archive or lists the
272 archive contents. It reads the archive from the standard input. Any
273 non-option command line arguments are shell globbing patterns; only
274 files in the archive whose names match one or more of those patterns are
275 copied from the archive. Unlike in the shell, an initial `.' in a
276 filename does match a wildcard at the start of a pattern, and a `/' in a
277 filename can match wildcards. If no patterns are given, all files are
278 extracted. @xref{Options}.
281 cpio @{-i|--extract@} [-bcdfmnrtsuvBSV] [-C bytes] [-E file]
282 [-H format] [-M message] [-R [user][:.][group]]
283 [-I [[user@@]host:]archive] [-F [[user@@]host:]archive]
284 [--file=[[user@@]host:]archive] [--make-directories]
285 [--nonmatching] [--preserve-modification-time]
286 [--numeric-uid-gid] [--rename] [--list] [--swap-bytes] [--swap]
287 [--dot] [--unconditional] [--verbose] [--block-size=blocks]
288 [--swap-halfwords] [--io-size=bytes] [--pattern-file=file]
289 [--format=format] [--owner=[user][:.][group]]
290 [--no-preserve-owner] [--message=message] [--help] [--version]
291 [--absolute-filenames] [--sparse] [-only-verify-crc] [-quiet]
292 [--rsh-command=command] [pattern...] [< archive]
295 @node Copy-pass mode, Options, Copy-in mode, Invoking `cpio'
296 @comment node-name, next, previous, up
297 @section Copy-pass mode
299 In copy-pass mode, cpio copies files from one directory tree to
300 another, combining the copy-out and copy-in steps without actually
301 using an archive. It reads the list of files to copy from the
302 standard input; the directory into which it will copy them is given as
303 a non-option argument.
307 cpio @{-p|--pass-through@} [-0adlmuvLV] [-R [user][:.][group]]
308 [--null] [--reset-access-time] [--make-directories] [--link]
309 [--preserve-modification-time] [--unconditional] [--verbose]
310 [--dot] [--dereference] [--owner=[user][:.][group]] [--sparse]
311 [--no-preserve-owner] [--help] [--version] destination-directory
317 @node Options, , Copy-pass mode, Invoking `cpio'
318 @comment node-name, next, previous, up
326 Read a list of filenames terminated by a null character, instead of a
327 newline, so that files whose names contain newlines can be archived.
328 GNU find is one way to produce a list of null-terminated filenames.
329 This option may be used in copy-out and copy-pass modes.
331 @item -a, --reset-access-time
332 Reset the access times of files after reading them, so
333 that it does not look like they have just been read.
336 Append to an existing archive. Only works in copy-out
337 mode. The archive must be a disk file specified with
338 the -O or -F (--file) option.
341 Swap both halfwords of words and bytes of halfwords in the data.
342 Equivalent to -sS. This option may be used in copy-in mode. Use this
343 option to convert 32-bit integers between big-endian and little-endian
347 Set the I/O block size to 5120 bytes. Initially the
348 block size is 512 bytes.
350 @item --block-size=BLOCK-SIZE
351 Set the I/O block size to BLOCK-SIZE * 512 bytes.
354 Use the old portable (ASCII) archive format.
356 @item -C IO-SIZE, --io-size=IO-SIZE
357 Set the I/O block size to IO-SIZE bytes.
359 @item -d, --make-directories
360 Create leading directories where needed.
362 @item -E FILE, --pattern-file=FILE
363 Read additional patterns specifying filenames to extract or list from
364 FILE. The lines of FILE are treated as if they had been non-option
365 arguments to cpio. This option is used in copy-in mode,
367 @item -f, --nonmatching
368 Only copy files that do not match any of the given
371 @item -F, --file=archive
372 Archive filename to use instead of standard input or output. To use a
373 tape drive on another machine as the archive, use a filename that starts
374 with `HOSTNAME:'. The hostname can be preceded by a username and an
375 `@@' to access the remote tape drive as that user, if you have
376 permission to do so (typically an entry in that user's `~/.rhosts'
380 With -F, -I, or -O, take the archive file name to be a
381 local file even if it contains a colon, which would
382 ordinarily indicate a remote host name.
384 @item -H FORMAT, --format=FORMAT
385 Use archive format FORMAT. The valid formats are listed below; the same
386 names are also recognized in all-caps. The default in copy-in mode is
387 to automatically detect the archive format, and in copy-out mode is
392 The obsolete binary format.
395 The old (POSIX.1) portable format.
398 The new (SVR4) portable format, which supports file systems having more
402 The new (SVR4) portable format with a checksum added.
408 The POSIX.1 tar format. Also recognizes GNU tar archives, which are
409 similar but not identical.
412 The obsolete binary format used by HPUX's cpio (which stores device
416 The portable format used by HPUX's cpio (which stores device files
425 Archive filename to use instead of standard input. To use a tape drive
426 on another machine as the archive, use a filename that starts with
427 `HOSTNAME:'. The hostname can be preceded by a username and an `@@' to
428 access the remote tape drive as that user, if you have permission to do
429 so (typically an entry in that user's `~/.rhosts' file).
432 Ignored; for compatibility with other versions of cpio.
435 Link files instead of copying them, when possible.
437 @item -L, --dereference
438 Copy the file that a symbolic link points to, rather than the symbolic
441 @item -m, --preserve-modification-time
442 Retain previous file modification times when creating files.
444 @item -M MESSAGE, --message=MESSAGE
445 Print MESSAGE when the end of a volume of the backup media (such as a
446 tape or a floppy disk) is reached, to prompt the user to insert a new
447 volume. If MESSAGE contains the string "%d", it is replaced by the
448 current volume number (starting at 1).
450 @item -n, --numeric-uid-gid
451 Show numeric UID and GID instead of translating them into names when using the
452 @samp{--verbose option}.
454 @item --absolute-filenames
455 Do not strip leading file name components that contain ".." and
456 leading slashes from file names in copy-in mode
458 @item --no-preserve-owner
459 Do not change the ownership of the files; leave them owned by the user
460 extracting them. This is the default for non-root users, so that users
461 on System V don't inadvertantly give away files. This option can be
462 used in copy-in mode and copy-pass mode
465 Run in copy-out mode.
466 @xref{Copy-out mode}.
469 Archive filename to use instead of standard output. To use a tape drive
470 on another machine as the archive, use a filename that starts with
471 `HOSTNAME:'. The hostname can be preceded by a username and an `@@' to
472 access the remote tape drive as that user, if you have permission to do
473 so (typically an entry in that user's `~/.rhosts' file).
475 @item --only-verify-crc
476 Verify the CRC's of each file in the archive, when reading a CRC format
477 archive. Don't actually extract the files.
479 @item -p, --pass-through
480 Run in copy-pass mode.
481 @xref{Copy-pass mode}.
484 Do not print the number of blocks copied.
487 Interactively rename files.
489 @item -R [user][:.][group], --owner [user][:.][group]
490 Set the ownership of all files created to the specified user and/or
491 group in copy-out and copy-pass modes. Either the user, the group, or
492 both, must be present. If the group is omitted but the ":" or "."
493 separator is given, use the given user's login group. Only the
494 super-user can change files' ownership.
496 @item --rsh-command=COMMAND
497 Notifies cpio that is should use COMMAND to communicate with remote
500 @item -s, --swap-bytes
501 Swap the bytes of each halfword (pair of bytes) in the files.This option
502 can be used in copy-in mode.
504 @item -S, --swap-halfwords
505 Swap the halfwords of each word (4 bytes) in the files. This option may
506 be used in copy-in mode.
509 Write files with large blocks of zeros as sparse files. This option is
510 used in copy-in and copy-pass modes.
513 Print a table of contents of the input.
515 @item -u, --unconditional
516 Replace all files, without asking whether to replace
517 existing newer files with older files.
520 List the files processed, or with @samp{-t}, give an @samp{ls -l} style
521 table of contents listing. In a verbose table of contents of a ustar
522 archive, user and group names in the archive that do not exist on the
523 local system are replaced by the names that correspond locally to the
524 numeric UID and GID stored in the archive.
527 Print a @kbd{.} for each file processed.
530 Print the cpio program version number and exit.
534 @node Media, Concept Index, Invoking `cpio', Top
535 @comment node-name, next, previous, up
536 @chapter Magnetic Media
537 @cindex magnetic media
539 Archives are usually written on removable media--tape cartridges, mag
540 tapes, or floppy disks.
542 The amount of data a tape or disk holds depends not only on its size,
543 but also on how it is formatted. A 2400 foot long reel of mag tape
544 holds 40 megabytes of data when formated at 1600 bits per inch. The
545 physically smaller EXABYTE tape cartridge holds 2.3 gigabytes.
547 Magnetic media are re-usable--once the archive on a tape is no longer
548 needed, the archive can be erased and the tape or disk used over. Media
549 quality does deteriorate with use, however. Most tapes or disks should
550 be disgarded when they begin to produce data errors.
552 Magnetic media are written and erased using magnetic fields, and should
553 be protected from such fields to avoid damage to stored data. Sticking
554 a floppy disk to a filing cabinet using a magnet is probably not a good
558 @node Concept Index, , Media, Top
559 @comment node-name, next, previous, up
560 @unnumbered Concept Index