Virgin import of GNU cpio v2.4.2.

svn path=/vendor/cpio/dist/; revision=24434
svn path=/vendor/cpio/2.4.2/; revision=24436; tag=vendor/misc-GNU/cpio/2.4.2

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