--- /dev/null
+.TH CPIO 1L \" -*- nroff -*-
+.SH NAME
+cpio \- copy files to and from archives
+.SH SYNOPSIS
+\&\fBCopy-out mode\fR
+.PP
+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. see \*(L"Options\*(R".
+.PP
+.B cpio
+{\-o|\-\-create} [\-0acvABLV] [\-C bytes] [\-H format]
+[\-M message] [\-O [[user@]host:]archive] [\-F [[user@]host:]archive]
+[\-\-file=[[user@]host:]archive] [\-\-format=format]
+[\-\-message=message][\-\-null] [\-\-reset\-access\-time] [\-\-verbose]
+[\-\-dot] [\-\-append] [\-\-block\-size=blocks] [\-\-dereference]
+[\-\-io\-size=bytes] [\-\-rsh\-command=command] [\-\-help] [\-\-version]
+< name-list [> archive]
+.PP
+\&\fBCopy-in mode\fR
+.PP
+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 `\fB.\fR' in a
+filename does match a wildcard at the start of a pattern, and a `\fB/\fR' in a
+filename can match wildcards. If no patterns are given, all files are
+extracted. see \*(L"Options\*(R".
+.PP
+.B 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]
+[\-\-absolute\-filenames] [\-\-sparse] [\-only\-verify\-crc] [\-quiet]
+[\-\-rsh\-command=command] [pattern...] [< archive]
+.PP
+\&\fBCopy-pass mode\fR
+.PP
+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. see \*(L"Options\*(R".
+.PP
+.B 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
+.PP
+.SH DESCRIPTION
+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.
+.PP
+Following archive formats are supported: 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.
+.PP
+.SH OPTIONS
+`\fB\-0, \-\-null\fR'
+Read a list of filenames terminated by a null character, instead
+of a newline, so that files whose names contain newlines can be
+archived. \s-1GNU\s0 find is one way to produce a list of
+null-terminated filenames. This option may be used in copy-out
+and copy-pass modes.
+.PP
+`\fB\-a, \-\-reset\-access\-time\fR'
+Reset the access times of files after reading them, so that it
+does not look like they have just been read.
+.PP
+`\fB\-A, \-\-append\fR'
+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.
+.PP
+`\fB\-b, \-\-swap\fR'
+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.
+.PP
+`\fB\-B\fR'
+Set the I/O block size to 5120 bytes. Initially the block size is
+512 bytes.
+.PP
+`\fB\-\-block\-size=BLOCK\-SIZE\fR'
+Set the I/O block size to BLOCK-SIZE * 512 bytes.
+.PP
+`\fB\-c\fR'
+Identical to \*(L"\-H newc\*(R", use the new (\s-1SVR4\s0) portable format.
+If you wish the old portable (\s-1ASCII\s0) archive format, use \*(L"\-H odc\*(R" instead.
+.PP
+`\fB\-C \s-1IO\-SIZE\s0, \-\-io\-size=IO\-SIZE\fR'
+Set the I/O block size to IO-SIZE bytes.
+.PP
+`\fB\-d, \-\-make\-directories\fR'
+Create leading directories where needed.
+.PP
+`\fB\-E \s-1FILE\s0, \-\-pattern\-file=FILE\fR'
+Read additional patterns specifying filenames to extract or list
+from \s-1FILE\s0. The lines of \s-1FILE\s0 are treated as if they had been
+non-option arguments to cpio. This option is used in copy-in mode,
+.PP
+`\fB\-f, \-\-nonmatching\fR'
+Only copy files that do not match any of the given patterns.
+.PP
+`\fB\-F, \-\-file=archive\fR'
+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 `\fB\s-1HOSTNAME:\s0\fR'. The hostname can be preceded by a
+username and an `\fB@\fR' to access the remote tape drive as that user,
+if you have permission to do so (typically an entry in that user's
+`\fB~/.rhosts\fR' file).
+.PP
+`\fB\-\-force\-local\fR'
+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.
+.PP
+`\fB\-H \s-1FORMAT\s0, \-\-format=FORMAT\fR'
+Use archive format \s-1FORMAT\s0. 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 `\fBbin\fR'.
+.PP
+`\fBbin\fR'
+The obsolete binary format.
+.PP
+`\fBodc\fR'
+The old (\s-1POSIX\s0.1) portable format.
+.PP
+`\fBnewc\fR'
+The new (\s-1SVR4\s0) portable format, which supports file systems
+having more than 65536 i\-nodes.
+.PP
+`\fBcrc\fR'
+The new (\s-1SVR4\s0) portable format with a checksum added.
+.PP
+`\fBtar\fR'
+The old tar format.
+.PP
+`\fBustar\fR'
+The \s-1POSIX\s0.1 tar format. Also recognizes \s-1GNU\s0 tar archives,
+which are similar but not identical.
+.PP
+`\fBhpbin\fR'
+The obsolete binary format used by \s-1HPUX\s0's cpio (which stores
+device files differently).
+.PP
+`\fBhpodc\fR'
+The portable format used by \s-1HPUX\s0's cpio (which stores device
+files differently).
+.PP
+`\fB\-i, \-\-extract\fR'
+Run in copy-in mode. see \*(L"Copy\-in mode\*(R".
+.PP
+`\fB\-I archive\fR'
+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 `\fB\s-1HOSTNAME:\s0\fR'. The hostname can be preceded by a
+username and an `\fB@\fR' to access the remote tape drive as that user,
+if you have permission to do so (typically an entry in that user's
+`\fB~/.rhosts\fR' file).
+.PP
+`\fB\-k\fR'
+Ignored; for compatibility with other versions of cpio.
+.PP
+`\fB\-l, \-\-link\fR'
+Link files instead of copying them, when possible.
+.PP
+`\fB\-L, \-\-dereference\fR'
+Copy the file that a symbolic link points to, rather than the
+symbolic link itself.
+.PP
+`\fB\-m, \-\-preserve\-modification\-time\fR'
+Retain previous file modification times when creating files.
+.PP
+`\fB\-M \s-1MESSAGE\s0, \-\-message=MESSAGE\fR'
+Print \s-1MESSAGE\s0 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 \s-1MESSAGE\s0 contains the string \*(L"%d\*(R", it is
+replaced by the current volume number (starting at 1).
+.PP
+`\fB\-n, \-\-numeric\-uid\-gid\fR'
+Show numeric \s-1UID\s0 and \s-1GID\s0 instead of translating them into names
+when using the `\fB\-\-verbose option\fR'.
+.PP
+`\fB\-\-absolute\-filenames\fR'
+Do not strip leading file name components that contain \*(L"..\*(R"
+and leading slashes from file names in copy-in mode
+.PP
+`\fB\-\-no\-preserve\-owner\fR'
+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
+.PP
+`\fB\-o, \-\-create\fR'
+Run in copy-out mode. see \*(L"Copy\-out mode\*(R".
+.PP
+`\fB\-O archive\fR'
+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 `\fB\s-1HOSTNAME:\s0\fR'. The hostname can be preceded by a
+username and an `\fB@\fR' to access the remote tape drive as that user,
+if you have permission to do so (typically an entry in that user's
+`\fB~/.rhosts\fR' file).
+.PP
+`\fB\-\-only\-verify\-crc\fR'
+Verify the \s-1CRC\s0's of each file in the archive, when reading a \s-1CRC\s0
+format archive. Don't actually extract the files.
+.PP
+`\fB\-p, \-\-pass\-through\fR'
+Run in copy-pass mode. see \*(L"Copy\-pass mode\*(R".
+.PP
+`\fB\-\-quiet\fR'
+Do not print the number of blocks copied.
+.PP
+`\fB\-r, \-\-rename\fR'
+Interactively rename files.
+.PP
+`\fB\-R [user][:.][group], \-\-owner [user][:.][group]\fR'
+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
+\&\*(L":\*(R" or \*(L".\*(R" separator is given, use the given user's login group.
+Only the super-user can change files' ownership.
+.PP
+`\fB\-\-rsh\-command=COMMAND\fR'
+Notifies cpio that is should use \s-1COMMAND\s0 to communicate with remote
+devices.
+.PP
+`\fB\-s, \-\-swap\-bytes\fR'
+Swap the bytes of each halfword (pair of bytes) in the files.This
+option can be used in copy-in mode.
+.PP
+`\fB\-S, \-\-swap\-halfwords\fR'
+Swap the halfwords of each word (4 bytes) in the files. This
+option may be used in copy-in mode.
+.PP
+`\fB\-\-sparse\fR'
+Write files with large blocks of zeros as sparse files. This
+option is used in copy-in and copy-pass modes.
+.PP
+`\fB\-t, \-\-list\fR'
+Print a table of contents of the input.
+.PP
+`\fB\-u, \-\-unconditional\fR'
+Replace all files, without asking whether to replace existing
+newer files with older files.
+.PP
+`\fB\-v, \-\-verbose\fR'
+List the files processed, or with `\fB\-t\fR', give an `\fBls \-l\fR' 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 \s-1UID\s0 and \s-1GID\s0 stored in the
+archive.
+.PP
+`\fB\-V \-\-dot\fR'
+Print a `\fB.\fR' for each file processed.
+.PP
+`\fB\-\-version\fR'
+Print the cpio program version number and exit.
+.PP
+.SH EXAMPLES
+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 `\fB\-F\fR' option.
+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.
+.PP
+.B % ls | cpio \-ov > directory.cpio
+.PP
+The `\fB\-o\fR' option creates the archive, and the `\fB\-v\fR' option prints the
+names of the files archived as they are added. Notice that the options
+can be put together after a single `\fB\-\fR' or can be placed separately on
+the command line. The `\fB>\fR' redirects the cpio output to the file
+`\fBdirectory.cpio\fR'.
+.PP
+If you wanted to archive an entire directory tree, the find command
+can provide the file list to cpio:
+.PP
+.B % find . \-print \-depth | cpio \-ov > tree.cpio
+.PP
+This will take all the files in the current directory, the
+directories below and place them in the archive tree.cpio. Again the
+`\fB\-o\fR' creates an archive, and the `\fB\-v\fR' option shows you the name of the
+files as they are archived. see \*(L"Copy\-out mode\*(R". Using the `\fB.\fR' 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 `\fB\-depth\fR' option forces `\fBfind\fR' 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.
+.PP
+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.
+.PP
+.B % cpio \-iv < directory.cpio
+.PP
+This will retrieve the files archived in the file directory.cpio and
+place them in the present directory. The `\fB\-i\fR' option extracts the
+archive and the `\fB\-v\fR' shows the file names as they are extracted. If
+you are dealing with an archived directory tree, you need to use the
+`\fB\-d\fR' option to create directories as necessary, something like:
+.PP
+.B % cpio \-idv < tree.cpio
+.PP
+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. see \*(L"Copy\-in mode\*(R".
+.PP
+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. see \*(L"Copy\-pass mode\*(R".
+.PP
+.B % find . \-depth \-print0 | cpio \-\-null \-pvd new-dir
+.PP
+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 `\fB\-print0\fR' available with \s-1GNU\s0 find, combined with the `\fB\-\-null\fR'
+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 `\fB\-p\fR', which tells cpio to pass the files it
+finds to the directory `\fBnew-dir\fR'.
+
+.SH BUGS
+The GNU folks, in general, abhor man pages, and create info documents instead. The maintainer of
+.B cpio
+falls
+into this category. Thus this man page may not be complete, nor current, and was included in the Red Hat
+CVS tree because man is a great tool :).
+.PP
+.SH REPORTING BUGS
+Please report bugs via https://bugzilla.redhat.com.
+.PP
+.SH SEE ALSO
+The full documentation for
+.B cpio
+is maintained as a Texinfo manual. If the
+.B info
+and
+.B cpio
+programs are properly installed at your site, the command
+.IP
+.B info cpio
+.PP
+should give you access to the complete manual. The online copy of the documentation
+is available at the following address:
+.PP
+http://www.gnu.org/software/cpio/manual
+
projects / product / upstream / cpio.git / commitdiff