diff --git a/contrib/cpio/cpio.texi b/contrib/cpio/cpio.texi new file mode 100644 index 000000000000..6b0fd45c519f --- /dev/null +++ b/contrib/cpio/cpio.texi @@ -0,0 +1,558 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename cpio.info +@settitle cpio +@setchapternewpage off +@set VERSION GNU cpio 2.4 +@set RELEASEDATE November 1995 +@c %**end of header + +@ifinfo +@format +START-INFO-DIR-ENTRY +* cpio: (cpio). Making tape (or disk) archives. +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@ifinfo +This file documents @value{VERSION}. + +Copyright (C) 1995 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph + + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Foundation. +@end ifinfo + + +@titlepage +@title GNU CPIO +@subtitle @value{VERSION} @value{RELEASEDATE} +@author by Robert Carleton +@c copyright page +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1995 Free Software Foundation, Inc. +@sp 2 +This is the first edition of the GNU cpio documentation,@* +and is consistent with @value{VERSION}.@* +@sp 2 +Published by the Free Software Foundation @* +59 Temple Place - Suite 330, @* +Boston, MA 02111-1307, USA @* + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation +approved by the Free Software Foundation. +@end titlepage + +@ifinfo +@node Top, Introduction, (dir), (dir) +@comment node-name, next, previous, up +@top + +GNU cpio is a tool for creating and extracting archives, or copying +files from one place to another. It handles a number of cpio formats as +well as reading and writing tar files. This is the first edition of the +GNU cpio documentation and is consistant with @value{VERSION}. + +@menu +* Introduction:: +* Tutorial:: Getting started. +* Invoking `cpio':: How to invoke `cpio'. +* Media:: Using tapes and other archive media. +* Concept Index:: Concept index. + + --- The Detailed Node Listing --- + +Invoking cpio + +* Copy-out mode:: +* Copy-in mode:: +* Copy-pass mode:: +* Options:: +@end menu + +@end ifinfo + +@node Introduction, Tutorial, Top, Top +@comment node-name, next, previous, up +@chapter Introduction + +GNU cpio copies files into or out of a cpio or tar archive, The archive +can be another file on the disk, a magnetic tape, or a pipe. + +GNU cpio supports the following archive formats: binary, old ASCII, new +ASCII, crc, HPUX binary, HPUX old ASCII, old tar, and POSIX.1 tar. The +tar format is provided for compatability with the tar program. By +default, cpio creates binary format archives, for compatibility with +older cpio programs. When extracting from archives, cpio automatically +recognizes which kind of archive it is reading and can read archives +created on machines with a different byte-order. + +@node Tutorial, Invoking `cpio', Introduction, Top +@comment node-name, next, previous, up +@chapter Tutorial +@cindex creating a cpio archive +@cindex extracting a cpio archive +@cindex copying directory structures +@cindex passing directory structures + + +GNU cpio performs three primary functions. Copying files to an +archive, Extracting files from an archive, and passing files to another +directory tree. An archive can be a file on disk, one or more floppy +disks, or one or more tapes. + +When creating an archive, cpio takes the list of files to be processed +from the standard input, and then sends the archive to the standard +output, or to the device defined by the @samp{-F} option. +@xref{Copy-out mode}. Usually find or ls is used to provide this list +to the standard input. In the following example you can see the +possibilities for archiving the contents of a single directory. + + +@example +@cartouche +% ls | cpio -ov > directory.cpio +@end cartouche +@end example + +The @samp{-o} option creates the archive, and the @samp{-v} option +prints the names of the files archived as they are added. Notice that +the options can be put together after a single @samp{-} or can be placed +separately on the command line. The @samp{>} redirects the cpio output +to the file @samp{directory.cpio}. + + +If you wanted to archive an entire directory tree, the find command can +provide the file list to cpio: + + +@example +@cartouche +% find . -print -depth | cpio -ov > tree.cpio +@end cartouche +@end example + + +This will take all the files in the current directory, the directories +below and place them in the archive tree.cpio. Again the @samp{-o} +creates an archive, and the @samp{-v} option shows you the name of the +files as they are archived. @xref{Copy-out mode}. Using the `.' in the +find statement will give you more flexibility when doing restores, as it +will save file names with a relative path vice a hard wired, absolute +path. The @samp{-depth} option forces @samp{find} to print of the +entries in a directory before printing the directory itself. This +limits the effects of restrictive directory permissions by printing the +directory entries in a directory before the directory name itself. + + + + +Extracting an archive requires a bit more thought because cpio will not +create directories by default. Another characteristic, is it will not +overwrite existing files unless you tell it to. + + +@example +@cartouche +% cpio -iv < directory.cpio +@end cartouche +@end example + +This will retrieve the files archived in the file directory.cpio and +place them in the present directory. The @samp{-i} option extracts the +archive and the @samp{-v} shows the file names as they are extracted. +If you are dealing with an archived directory tree, you need to use the +@samp{-d} option to create directories as necessary, something like: + +@example +@cartouche +% cpio -idv < tree.cpio +@end cartouche +@end example + +This will take the contents of the archive tree.cpio and extract it to +the current directory. If you try to extract the files on top of files +of the same name that already exist (and have the same or later +modification time) cpio will not extract the file unless told to do so +by the -u option. @xref{Copy-in mode}. + + +In copy-pass mode, cpio copies files from one directory tree to another, +combining the copy-out and copy-in steps without actually using an +archive. It reads the list of files to copy from the standard input; +the directory into which it will copy them is given as a non-option +argument. @xref{Copy-pass mode}. + +@example +@cartouche +% find . -depth -print0 | cpio --null -pvd new-dir +@end cartouche +@end example + + +The example shows copying the files of the present directory, and +sub-directories to a new directory called new-dir. Some new options are +the @samp{-print0} available with GNU find, combined with the +@samp{--null} option of cpio. These two options act together to send +file names between find and cpio, even if special characters are +embedded in the file names. Another is @samp{-p}, which tells cpio to +pass the files it finds to the directory @samp{new-dir}. + +@node Invoking `cpio', Media, Tutorial, Top +@comment node-name, next, previous, up +@chapter Invoking cpio +@cindex invoking cpio +@cindex command line options + +@menu +* Copy-out mode:: +* Copy-in mode:: +* Copy-pass mode:: +* Options:: +@end menu + +@node Copy-out mode, Copy-in mode, Invoking `cpio', Invoking `cpio' +@comment node-name, next, previous, up +@section Copy-out mode + +In copy-out mode, cpio copies files into an archive. It reads a list +of filenames, one per line, on the standard input, and writes the +archive onto the standard output. A typical way to generate the list +of filenames is with the find command; you should give find the -depth +option to minimize problems with permissions on directories that are +unreadable. +@xref{Options}. + +@example +cpio @{-o|--create@} [-0acvABLV] [-C bytes] [-H format] +[-M message] [-O [[user@@]host:]archive] [-F [[user@@]host:]archive] +[--file=[[user@@]host:]archive] [--format=format] [--sparse] +[--message=message][--null] [--reset-access-time] [--verbose] +[--dot] [--append] [--block-size=blocks] [--dereference] +[--io-size=bytes] [--help] [--version] < name-list [> archive] +@end example + +@node Copy-in mode, Copy-pass mode, Copy-out mode, Invoking `cpio' +@comment node-name, next, previous, up +@section Copy-in mode + +In copy-in mode, cpio copies files out of an archive or lists the +archive contents. It reads the archive from the standard input. Any +non-option command line arguments are shell globbing patterns; only +files in the archive whose names match one or more of those patterns are +copied from the archive. Unlike in the shell, an initial `.' in a +filename does match a wildcard at the start of a pattern, and a `/' in a +filename can match wildcards. If no patterns are given, all files are +extracted. @xref{Options}. + +@example +cpio @{-i|--extract@} [-bcdfmnrtsuvBSV] [-C bytes] [-E file] +[-H format] [-M message] [-R [user][:.][group]] +[-I [[user@@]host:]archive] [-F [[user@@]host:]archive] +[--file=[[user@@]host:]archive] [--make-directories] +[--nonmatching] [--preserve-modification-time] +[--numeric-uid-gid] [--rename] [--list] [--swap-bytes] [--swap] +[--dot] [--unconditional] [--verbose] [--block-size=blocks] +[--swap-halfwords] [--io-size=bytes] [--pattern-file=file] +[--format=format] [--owner=[user][:.][group]] +[--no- preserve-owner] [--message=message] [--help] [--version] +[-no-abosolute-filenames] [-only-verify-crc] [-quiet] +[pattern...] [< archive] +@end example + +@node Copy-pass mode, Options, Copy-in mode, Invoking `cpio' +@comment node-name, next, previous, up +@section Copy-pass mode + +In copy-pass mode, cpio copies files from one directory tree to +another, combining the copy-out and copy-in steps without actually +using an archive. It reads the list of files to copy from the +standard input; the directory into which it will copy them is given as +a non-option argument. +@xref{Options}. + +@example +cpio @{-p|--pass-through@} [-0adlmuvLV] [-R [user][:.][group]] +[--null] [--reset-access-time] [--make-directories] [--link] +[--preserve-modification-time] [--unconditional] [--verbose] +[--dot] [--dereference] [--owner=[user][:.][group]] [--sparse] +[--no-preserve-owner] [--help] [--version] destination-directory +< name-list +@end example + + + +@node Options, , Copy-pass mode, Invoking `cpio' +@comment node-name, next, previous, up +@section Options + + +@table @code + + +@item -0, --null +Read a list of filenames terminated by a null character, instead of a +newline, so that files whose names contain newlines can be archived. +GNU find is one way to produce a list of null-terminated filenames. +This option may be used in copy-out and copy-pass modes. + +@item -a, --reset-access-time +Reset the access times of files after reading them, so +that it does not look like they have just been read. + +@item -A, --append +Append to an existing archive. Only works in copy-out +mode. The archive must be a disk file specified with +the -O or -F (--file) option. + +@item -b, --swap +Swap both halfwords of words and bytes of halfwords in the data. +Equivalent to -sS. This option may be used in copy-in mode. Use this +option to convert 32-bit integers between big-endian and little-endian +machines. + +@item -B +Set the I/O block size to 5120 bytes. Initially the +block size is 512 bytes. + +@item --block-size=BLOCK-SIZE +Set the I/O block size to BLOCK-SIZE * 512 bytes. + +@item -c +Use the old portable (ASCII) archive format. + +@item -C IO-SIZE, --io-size=IO-SIZE +Set the I/O block size to IO-SIZE bytes. + +@item -d, --make-directories +Create leading directories where needed. + +@item -E FILE, --pattern-file=FILE +Read additional patterns specifying filenames to extract or list from +FILE. The lines of FILE are treated as if they had been non-option +arguments to cpio. This option is used in copy-in mode, + +@item -f, --nonmatching +Only copy files that do not match any of the given +patterns. + +@item -F, --file=archive +Archive filename to use instead of standard input or output. To use a +tape drive on another machine as the archive, use a filename that starts +with `HOSTNAME:'. The hostname can be preceded by a username and an +`@@' to access the remote tape drive as that user, if you have +permission to do so (typically an entry in that user's `~/.rhosts' +file). + +@item --force-local +With -F, -I, or -O, take the archive file name to be a +local file even if it contains a colon, which would +ordinarily indicate a remote host name. + +@item -H FORMAT, --format=FORMAT +Use archive format FORMAT. The valid formats are listed below; the same +names are also recognized in all-caps. The default in copy-in mode is +to automatically detect the archive format, and in copy-out mode is +@samp{bin}. + +@table @samp +@item bin +The obsolete binary format. + +@item odc +The old (POSIX.1) portable format. + +@item newc +The new (SVR4) portable format, which supports file systems having more +than 65536 i-nodes. + +@item crc +The new (SVR4) portable format with a checksum added. + +@item tar +The old tar format. + +@item ustar +The POSIX.1 tar format. Also recognizes GNU tar archives, which are +similar but not identical. + +@item hpbin +The obsolete binary format used by HPUX's cpio (which stores device +files differently). + +@item hpodc +The portable format used by HPUX's cpio (which stores device files +differently). +@end table + +@item -i, --extract +Run in copy-in mode. +@xref{Copy-in mode}. + +@item -I archive +Archive filename to use instead of standard input. To use a tape drive +on another machine as the archive, use a filename that starts with +`HOSTNAME:'. The hostname can be preceded by a username and an `@@' to +access the remote tape drive as that user, if you have permission to do +so (typically an entry in that user's `~/.rhosts' file). + +@item -k +Ignored; for compatibility with other versions of cpio. + +@item -l, --link +Link files instead of copying them, when possible. + +@item -L, --dereference +Copy the file that a symbolic link points to, rather than the symbolic +link itself. + +@item -m, --preserve-modification-time +Retain previous file modification times when creating files. + +@item -M MESSAGE, --message=MESSAGE +Print MESSAGE when the end of a volume of the backup media (such as a +tape or a floppy disk) is reached, to prompt the user to insert a new +volume. If MESSAGE contains the string "%d", it is replaced by the +current volume number (starting at 1). + +@item -n, --numeric-uid-gid +Show numeric UID and GID instead of translating them into names when using the +@samp{--verbose option}. + +@item --no-absolute-filenames +Create all files relative to the current directory in copy-in mode, even +if they have an absolute file name in the archive. + +@item --no-preserve-owner +Do not change the ownership of the files; leave them owned by the user +extracting them. This is the default for non-root users, so that users +on System V don't inadvertantly give away files. This option can be +used in copy-in mode and copy-pass mode + +@item -o, --create +Run in copy-out mode. +@xref{Copy-out mode}. + +@item -O archive +Archive filename to use instead of standard output. To use a tape drive +on another machine as the archive, use a filename that starts with +`HOSTNAME:'. The hostname can be preceded by a username and an `@@' to +access the remote tape drive as that user, if you have permission to do +so (typically an entry in that user's `~/.rhosts' file). + +@item --only-verify-crc +Verify the CRC's of each file in the archive, when reading a CRC format +archive. Don't actually extract the files. + +@item -p, --pass-through +Run in copy-pass mode. +@xref{Copy-pass mode}. + +@item --quiet +Do not print the number of blocks copied. + +@item -r, --rename +Interactively rename files. + +@item -R [user][:.][group], --owner [user][:.][group] +Set the ownership of all files created to the specified user and/or +group in copy-out and copy-pass modes. Either the user, the group, or +both, must be present. If the group is omitted but the ":" or "." +separator is given, use the given user's login group. Only the +super-user can change files' ownership. + +@item -s, --swap-bytes +Swap the bytes of each halfword (pair of bytes) in the files.This option +can be used in copy-in mode. + +@item -S, --swap-halfwords +Swap the halfwords of each word (4 bytes) in the files. This option may +be used in copy-in mode. + +@item --sparse +Write files with large blocks of zeros as sparse files. This option is +used in copy-out and copy-pass modes. + +@item -t, --list +Print a table of contents of the input. + +@item -u, --unconditional +Replace all files, without asking whether to replace +existing newer files with older files. + +@item -v, --verbose +List the files processed, or with @samp{-t}, give an @samp{ls -l} style +table of contents listing. In a verbose table of contents of a ustar +archive, user and group names in the archive that do not exist on the +local system are replaced by the names that correspond locally to the +numeric UID and GID stored in the archive. + +@item -V --dot +Print a @kbd{.} for each file processed. + +@item --version +Print the cpio program version number and exit. +@end table + + +@node Media, Concept Index, Invoking `cpio', Top +@comment node-name, next, previous, up +@chapter Magnetic Media +@cindex magnetic media + +Archives are usually written on removable media--tape cartridges, mag +tapes, or floppy disks. + +The amount of data a tape or disk holds depends not only on its size, +but also on how it is formatted. A 2400 foot long reel of mag tape +holds 40 megabytes of data when formated at 1600 bits per inch. The +physically smaller EXABYTE tape cartridge holds 2.3 gigabytes. + +Magnetic media are re-usable--once the archive on a tape is no longer +needed, the archive can be erased and the tape or disk used over. Media +quality does deteriorate with use, however. Most tapes or disks should +be disgarded when they begin to produce data errors. + +Magnetic media are written and erased using magnetic fields, and should +be protected from such fields to avoid damage to stored data. Sticking +a floppy disk to a filing cabinet using a magnet is probably not a good +idea. + + +@node Concept Index, , Media, Top +@comment node-name, next, previous, up +@unnumbered Concept Index +@printindex cp +@contents +@bye