.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.\" $Id: restore.8.in,v 1.27 2002/06/08 07:10:37 stelian Exp $
+.\" $Id: restore.8.in,v 1.28 2002/07/24 14:12:00 stelian Exp $
.\"
-.Dd __DATE__
-.Dt RESTORE 8
-.Os "restore __VERSION__"
-.Sh NAME
-.Nm restore
-.Nd "restore files or file systems from backups made with dump"
-.Sh SYNOPSIS
-.Nm restore
-.Fl C
-.Op Fl cdklMvVy
-.Op Fl b Ar blocksize
-.Op Fl D Ar filesystem
-.Op Fl f Ar file
-.Op Fl F Ar script
-.Op Fl L Ar limit
-.Op Fl s Ar fileno
-.Op Fl T Ar directory
-.Nm restore
-.Fl i
-.Op Fl acdhklmMNouvVy
-.Op Fl A Ar file
-.Op Fl b Ar blocksize
-.Op Fl f Ar file
-.Op Fl F Ar script
-.Op Fl Q Ar file
-.Op Fl s Ar fileno
-.Op Fl T Ar directory
-.Nm restore
-.Fl P Ar file
-.Op Fl acdhklmMNuvVy
-.Op Fl A Ar file
-.Op Fl b Ar blocksize
-.Op Fl f Ar file
-.Op Fl F Ar script
-.Op Fl s Ar fileno
-.Op Fl T Ar directory
-.Op Fl X Ar filelist
-.Op file ...
-.Nm restore
-.Fl R
-.Op Fl cdklMNuvVy
-.Op Fl b Ar blocksize
-.Op Fl f Ar file
-.Op Fl F Ar script
-.Op Fl s Ar fileno
-.Op Fl T Ar directory
-.Nm restore
-.Fl r
-.Op Fl cdklMNuvVy
-.Op Fl b Ar blocksize
-.Op Fl f Ar file
-.Op Fl F Ar script
-.Op Fl s Ar fileno
-.Op Fl T Ar directory
-.Nm restore
-.Fl t
-.Op Fl cdhklMNuvVy
-.Op Fl A Ar file
-.Op Fl b Ar blocksize
-.Op Fl f Ar file
-.Op Fl F Ar script
-.Op Fl Q Ar file
-.Op Fl s Ar fileno
-.Op Fl T Ar directory
-.Op Fl X Ar filelist
-.Op file ...
-.Nm restore
-.Fl x
-.Op Fl adchklmMNouvVy
-.Op Fl A Ar file
-.Op Fl b Ar blocksize
-.Op Fl f Ar file
-.Op Fl F Ar script
-.Op Fl Q Ar file
-.Op Fl s Ar fileno
-.Op Fl T Ar directory
-.Op Fl X Ar filelist
-.Op file ...
-.Pp
-.in
-(The
-.Bx 4.3
-option syntax is implemented for backward compatibility but
-is not documented here.)
-.Sh DESCRIPTION
+.TH RESTORE 8 "version __VERSION__ of __DATE__" BSD "System management commands"
+.SH NAME
+restore \- restore files or file systems from backups made with dump
+.SH SYNOPSIS
+.B restore \-C
+[\fB\-cdklMvVy\fR]
+[\fB\-b \fIblocksize\fR]
+[\fB\-D \fIfilesystem\fR]
+[\fB\-f \fIfile\fR]
+[\fB\-F \fIscript\fR]
+[\fB\-L \fIlimit\fR]
+[\fB\-s \fIfileno\fR]
+[\fB\-T \fIdirectory\fR]
+.PP
+.B restore \-i
+[\fB\-acdhklmMNouvVy\fR]
+[\fB\-A \fIfile\fR]
+[\fB\-b \fIblocksize\fR]
+[\fB\-f \fIfile\fR]
+[\fB\-F \fIscript\fR]
+[\fB\-Q \fIfile\fR]
+[\fB\-s \fIfileno\fR]
+[\fB\-T \fIdirectory\fR]
+.PP
+.B restore \-P
+.I file
+[\fB\-acdhklmMNuvVy\fR]
+[\fB\-A \fIfile\fR]
+[\fB\-b \fIblocksize\fR]
+[\fB\-f \fIfile\fR]
+[\fB\-F \fIscript\fR]
+[\fB\-s \fIfileno\fR]
+[\fB\-T \fIdirectory\fR]
+[\fB\-X \fIfilelist\fR]
+[ \fIfile ... \fR]
+.PP
+.B restore \-R
+[\fB\-cdklMNuvVy\fR]
+[\fB\-b \fIblocksize\fR]
+[\fB\-f \fIfile\fR]
+[\fB\-F \fIscript\fR]
+[\fB\-s \fIfileno\fR]
+[\fB\-T \fIdirectory\fR]
+.PP
+.B restore \-r
+[\fB\-cdklMNuvVy\fR]
+[\fB\-b \fIblocksize\fR]
+[\fB\-f \fIfile\fR]
+[\fB\-F \fIscript\fR]
+[\fB\-s \fIfileno\fR]
+[\fB\-T \fIdirectory\fR]
+.PP
+.B restore \-t
+[\fB\-cdhklMNuvVy\fR]
+[\fB\-A \fIfile\fR]
+[\fB\-b \fIblocksize\fR]
+[\fB\-f \fIfile\fR]
+[\fB\-F \fIscript\fR]
+[\fB\-Q \fIfile\fR]
+[\fB\-s \fIfileno\fR]
+[\fB\-T \fIdirectory\fR]
+[\fB\-X \fIfilelist\fR]
+[ \fIfile ... \fR]
+.PP
+.B restore \-x
+[\fB\-adchklmMNouvVy\fR]
+[\fB\-A \fIfile\fR]
+[\fB\-b \fIblocksize\fR]
+[\fB\-f \fIfile\fR]
+[\fB\-F \fIscript\fR]
+[\fB\-Q \fIfile\fR]
+[\fB\-s \fIfileno\fR]
+[\fB\-T \fIdirectory\fR]
+[\fB\-X \fIfilelist\fR]
+[ \fIfile ... \fR]
+.PP
+(The 4.3BSD option syntax is implemented for backward compatibility but is not
+documented here.)
+.SH DESCRIPTION
The
-.Nm restore
+.B restore
command performs the inverse function of
-.Xr dump 8 .
-A full backup of a file system may be restored and
-subsequent incremental backups layered on top of it.
-Single files and
-directory subtrees may be restored from full or partial
-backups.
-.Nm Restore
-works across a network;
-to do this see the
-.Fl f
-flag described below.
-Other arguments to the command are file or directory
-names specifying the files that are to be restored.
-Unless the
-.Fl h
-flag is specified (see below),
-the appearance of a directory name refers to
+.BR dump (8).
+A full backup of a file system may be restored and subsequent incremental
+backups layered on top of it. Single files and directory subtrees may be
+restored from full or partial backups.
+.B Restore
+works across a network; to do this see the
+.B \-f
+flag described below. Other arguments to the command are file or directory
+names specifying the files that are to be restored. Unless the
+.B \-h
+flag is specified (see below), the appearance of a directory name refers to
the files and (recursively) subdirectories of that directory.
-.Pp
+.PP
Exactly one of the following flags is required:
-.Bl -tag -width Ds
-.It Fl C
+.TP
+.B \-C
This mode allows comparison of files from a dump.
-.Nm Restore
-reads the backup and compares its contents with files present on the
-disk.
-It first changes its working directory to the root of the filesystem
-that was dumped and compares the tape with the files in its new
-current directory.
-See also the
-.Fl L
+.B Restore
+reads the backup and compares its contents with files present on the disk. It
+first changes its working directory to the root of the filesystem that was
+dumped and compares the tape with the files in its new current directory. See
+also the
+.B \-L
flag described below.
-.It Fl i
-This mode allows interactive restoration of files from a dump.
-After reading in the directory information from the dump,
-.Nm restore
-provides a shell like interface that allows the user to move
-around the directory tree selecting files to be extracted.
-The available commands are given below;
-for those commands that require an argument,
-the default is the current directory.
-.Bl -tag -width Fl
-.It Ic add Op Ar arg
-The current directory or specified argument is added to the list of
-files to be extracted.
-If a directory is specified, then it and all its descendents are
-added to the extraction list
-(unless the
-.Fl h
-flag is specified on the command line).
-Files that are on the extraction list are prepended with a
-.Dq \&*
-when they are listed by
-.Ic ls .
-.It Ic \&cd Ar arg
+.TP
+.B \-i
+This mode allows interactive restoration of files from a dump. After reading in
+the directory information from the dump,
+.B restore
+provides a shell like interface that allows the user to move around the
+directory tree selecting files to be extracted. The available commands are
+given below; for those commands that require an argument, the default is the
+current directory.
+.RS
+.TP
+.B add \fR[\fIarg\fR]
+The current directory or specified argument is added to the list of files to be
+extracted. If a directory is specified, then it and all its descendents are
+added to the extraction list (unless the
+.B \-h
+flag is specified on the command line). Files that are on the extraction list
+are prepended with a \*(lq*\*(rq when they are listed by
+.BR ls .
+.TP
+.BI cd " arg"
Change the current working directory to the specified argument.
-.It Ic delete Op Ar arg
-The current directory or specified argument is deleted from the list of
-files to be extracted.
-If a directory is specified, then it and all its descendents are
-deleted from the extraction list
-(unless the
-.Fl h
-flag is specified on the command line).
-The most expedient way to extract most of the files from a directory
-is to add the directory to the extraction list and then delete
-those files that are not needed.
-.It Ic extract
-All files on the extraction list are extracted
-from the dump.
-.Nm Restore
-will ask which volume the user wishes to mount.
-The fastest way to extract a few files is to
-start with the last volume and work towards the first volume.
-.It Ic help
+.TP
+.B delete \fR[\fIarg\fR]
+The current directory or specified argument is deleted from the list of files
+to be extracted. If a directory is specified, then it and all its descendents
+are deleted from the extraction list (unless the
+.B \-h
+flag is specified on the command line). The most expedient way to extract most
+of the files from a directory is to add the directory to the extraction list
+and then delete those files that are not needed.
+.TP
+.B extract
+All files on the extraction list are extracted from the dump.
+.B Restore
+will ask which volume the user wishes to mount. The fastest way to extract a f
+ew files is to start with the last volume and work towards the first volume.
+.TP
+.B help
List a summary of the available commands.
-.It Ic \&ls Op Ar arg
-List the current or specified directory.
-Entries that are directories are appended with a
-.Dq \&* .
-Entries that have been marked for extraction are prepended with a ``*''.
-If the verbose
-flag is set, the inode number of each entry is also listed.
-.It Ic pwd
+.TP
+.B ls \fR[\fIarg\fR]
+List the current or specified directory. Entries that are directories are
+appended with a \*(lq/\*(rq. Entries that have been marked for extraction are
+prepended with a \*(lq*\*(rq. If the verbose flag is set, the inode number of
+each entry is also listed.
+.TP
+.B pwd
Print the full pathname of the current working directory.
-.It Ic quit
-Restore immediately exits,
-even if the extraction list is not empty.
-.It Ic setmodes
-All directories that have been added to the extraction list
-have their owner, modes, and times set;
-nothing is extracted from the dump.
-This is useful for cleaning up after a restore has been prematurely aborted.
-.It Ic verbose
+.TP
+.B quit
+.B Restore
+immediately exits, even if the extraction list is not empty.
+.TP
+.B setmodes
+All directories that have been added to the extraction list have their owner,
+modes, and times set; nothing is extracted from the dump. This is useful for
+cleaning up after a
+.B restore
+has been prematurely aborted.
+.TP
+.B verbose
The sense of the
-.Fl v
-flag is toggled.
-When set, the verbose flag causes the
-.Ic ls
-command to list the inode numbers of all entries.
-It also causes
-.Nm restore
+.B \-v
+flag is toggled. When set, the verbose flag causes the
+.B ls
+command to list the inode numbers of all entries. It also causes
+.B restore
to print out information about each file as it is extracted.
-.El
-.It Fl P Ar file
-.Nm Restore
+.RE
+.TP
+.BI \-P " file"
+.B Restore
creates a new Quick File Access file
-.Ar file
+.I file
from an existing dump file without restoring its contents.
-.It Fl R
-.Nm Restore
-requests a particular tape of a multi-volume set on which to restart
-a full restore
-(see the
-.Fl r
-flag below).
-This is useful if the restore has been interrupted.
-.It Fl r
-Restore (rebuild) a file system.
-The target file system should be made pristine with
-.Xr mke2fs 8 ,
+.TP
+.B \-R
+.B Restore
+requests a particular tape of a multi-volume set on which to restart a full
+restore (see the
+.B \-r
+flag below). This is useful if the restore has been interrupted.
+.TP
+.B \-r
+Restore (rebuild) a file system. The target file system should be made pristine
+with
+.BR mke2fs (8),
mounted, and the user
-.Xr cd Ns 'd
-into the pristine file system
-before starting the restoration of the initial level 0 backup. If the
-level 0 restores successfully, the
-.Fl r
-flag may be used to restore
-any necessary incremental backups on top of the level 0.
-The
-.Fl r
-flag precludes an interactive file extraction and can be
-detrimental to one's health (not to mention the disk) if not used carefully.
-An example:
-.Bd -literal -offset indent
-mke2fs /dev/sda1
-mount /dev/sda1 /mnt
-cd /mnt
-
-restore rf /dev/st0
-.Ed
-.Pp
+.BR cd 'd
+into the pristine file system before starting the restoration of the initial
+level 0 backup. If the level 0 restores successfully, the
+.B \-r
+flag may be used to restore any necessary incremental backups on top of the
+level 0. The
+.B \-r
+flag precludes an interactive file extraction and can be detrimental to one's
+health (not to mention the disk) if not used carefully. An example:
+.IP
+.RS 14
+.B mke2fs /dev/sda1
+.TP
+.B mount /dev/sda1 /mnt
+.TP
+.B cd /mnt
+.TP
+.B restore rf /dev/st0
+.RE
+.IP
Note that
-.Nm restore
+.B restore
leaves a file
-.Pa restoresymtable
-in the root directory to pass information between incremental
-restore passes.
-This file should be removed when the last incremental has been
-restored.
-.Pp
-.Nm Restore ,
+.I restoresymtable
+in the root directory to pass information between incremental restore passes.
+This file should be removed when the last incremental has been restored.
+.IP
+.BR Restore ,
in conjunction with
-.Xr mke2fs 8
+.BR mke2fs (8)
and
-.Xr dump 8 ,
-may be used to modify file system parameters
-such as size or block size.
-.It Fl t
-The names of the specified files are listed if they occur
-on the backup.
-If no file argument is given,
-the root directory is listed,
-which results in the entire content of the
-backup being listed,
-unless the
-.Fl h
-flag has been specified.
-Note that the
-.Fl t
+.BR dump (8),
+may be used to modify file system parameters such as size or block size.
+.TP
+.B \-t
+The names of the specified files are listed if they occur on the backup. If no
+file argument is given, the root directory is listed, which results in the
+entire content of the backup being listed, unless the
+.B \-h
+flag has been specified. Note that the
+.B \-t
flag replaces the function of the old
-.Xr dumpdir 8
-program.
-See also the
-.Fl X
+.BR dumpdir (8)
+program. See also the
+.B \-X
option below.
-.ne 1i
-.It Fl x
-The named files are read from the given media.
-If a named file matches a directory whose contents
-are on the backup
-and the
-.Fl h
-flag is not specified,
-the directory is recursively extracted.
-The owner, modification time,
-and mode are restored (if possible).
-If no file argument is given,
-the root directory is extracted,
-which results in the entire content of the
-backup being extracted,
-unless the
-.Fl h
-flag has been specified.
-See also the
-.Fl X
+.TP
+.B \-x
+The named files are read from the given media. If a named file matches a
+directory whose contents are on the backup and the
+.B \-h
+flag is not specified, the directory is recursively extracted. The owner,
+modification time, and mode are restored (if possible). If no file argument is
+given, the root directory is extracted, which results in the entire content of
+the backup being extracted, unless the
+.B \-h
+flag has been specified. See also the
+.B \-X
option below.
-.El
-.Pp
+.SH OPTIONS
The following additional options may be specified:
-.Bl -tag -width Ds
-.It Fl a
+.TP
+.B \-a
In
-.Fl i
+.B \-i
or
-.Fl x
+.B \-x
mode,
-.Nm restore
-does ask the user for the volume number on which the files to
-be extracted are supposed to be (in order to minimise the time
-be reading only the interesting volumes). The
-.Fl a
-option disables this behaviour and reads all the volumes starting
-with 1. This option is useful when the operator does not know on which
-volume the files to be extracted are and/or when he prefers the
-longer unattended mode rather than the shorter interactive mode.
-.It Fl A Ar archive_file
+.B restore
+does ask the user for the volume number on which the files to be extracted are
+supposed to be (in order to minimise the time by reading only the interesting
+volumes). The
+.B \-a
+option disables this behaviour and reads all the volumes starting with 1. This
+option is useful when the operator does not know on which volume the files to
+be extracted are and/or when he prefers the longer unattended mode rather than
+the shorter interactive mode.
+.TP
+.BI \-A " archive_file"
Read the table of contents from
-.Ar archive_file
+.I archive_file
instead of the media. This option can be used in combination with the
-.Fl t,
-.Fl i,
+.BR \-t ,
+.BR \-i ,
or
-.Fl x
-options, making it possible to check whether files are on the media
-without having to mount the media.
-.It Fl b Ar blocksize
-The number of kilobytes per dump record.
-If the
-.Fl b
+.B \-x
+options, making it possible to check whether files are on the media without
+having to mount the media.
+.TP
+.BI \-b " blocksize"
+The number of kilobytes per dump record. If the
+.B \-b
option is not specified,
-.Nm restore
+.B restore
tries to determine the media block size dynamically.
-.It Fl c
+.TP
+.B \-c
Normally,
-.Nm restore
-will try to determine dynamically whether the dump was made from an
-old (pre-4.4) or new format file system. The
-.Fl c
-flag disables this check, and only allows reading a dump in the old
-format.
-.It Fl d
+.B restore
+will try to determine dynamically whether the dump was made from an old
+(pre-4.4) or new format file system. The
+.B \-c
+flag disables this check, and only allows reading a dump in the old format.
+.TP
+.B \-d
The
-.Fl d
-(debug)
-flag causes
-.Nm restore
+.B \-d
+(debug) flag causes
+.B restore
to print debug information.
-.It Fl D Ar filesystem
+.TP
+.BI \-D " filesystem"
The
-.Fl D
+.B \-D
flag allows the user to specify the filesystem name when using
-.Nm restore
+.B restore
with the
-.Fl C
+.B \-C
option to check the backup.
-.It Fl f Ar file
+.TP
+.BI \-f " file"
Read the backup from
-.Ar file ;
-.Ar file
-may be a special device file
-like
-.Pa /dev/st0
+.IR file ;
+.I file
+may be a special device file like
+.I /dev/st0
(a tape drive),
-.Pa /dev/sda1
-(a disk drive),
-an ordinary file,
-or
-.Ql Fl
-(the standard input).
-If the name of the file is of the form
-.Dq host:file
+.I /dev/sda1
+(a disk drive), an ordinary file, or
+.I \-
+(the standard input). If the name of the file is of the form
+.I host:file
or
-.Dq user@host:file ,
-.Nm restore
+.IR user@host:file ,
+.B restore
reads from the named file on the remote host using
-.Xr rmt 8 .
-.Pp
-.It Fl F Ar script
-Run script at the beginning of each tape. The device name and the
-current volume number are passed on the command line.
-The script must return 0 if
-.Nm
+.BR rmt (8).
+.TP
+.BI \-F " script"
+Run script at the beginning of each tape. The device name and the current
+volume number are passed on the command line. The script must return 0 if
+.B restore
should continue without asking the user to change the tape, 1 if
-.Nm
-should continue but ask the user to change the tape.
-Any other exit code will cause
-.Nm
-to abort.
-For security reasons,
-.Nm
-reverts back to the real user ID and the real group ID before
-running the script.
-.It Fl h
-Extract the actual directory,
-rather than the files that it references.
-This prevents hierarchical restoration of complete subtrees
-from the dump.
-.It Fl k
-Use Kerberos authentication when contacting the remote tape server.
-(Only available if this options was enabled when
-.Nm restore
+.B restore
+should continue but ask the user to change the tape. Any other exit code will
+cause
+.B restore
+to abort. For security reasons,
+.B restore
+reverts back to the real user ID and the real group ID before running the
+script.
+.TP
+.B \-h
+Extract the actual directory, rather than the files that it references. This
+prevents hierarchical restoration of complete subtrees from the dump.
+.TP
+.B \-k
+Use Kerberos authentication when contacting the remote tape server. (Only
+available if this options was enabled when
+.B restore
was compiled.)
-.It Fl l
-When doing remote restores, assume the remote file is a
-regular file (instead of a tape device). If you're restoring
-a remote compressed file, you will need to specify this
-option or
-.Nm restore
+.TP
+.B \-l
+When doing remote restores, assume the remote file is a regular file (instead
+of a tape device). If you're restoring a remote compressed file, you will need
+to specify this option or
+.B restore
will fail to access it correctly.
-.It Fl L Ar limit
+.TP
+.BI \-L " limit"
The
-.Fl L
-flag allows the user to specify a maximal number of miscompares
-when using
-.Nm restore
+.B \-L
+flag allows the user to specify a maximal number of miscompares when using
+.B restore
with the
-.Fl C
+.B \-C
option to check the backup. If this limit is reached,
-.Nm restore
-will abort with an error message. A value of 0 (the default value)
-disables the check.
-.It Fl m
-Extract by inode numbers rather than by file name.
-This is useful if only a few files are being extracted,
-and one wants to avoid regenerating the complete pathname
-to the file.
-.It Fl M
-Enables the multi-volume feature (for reading dumps made using
-the
-.Fl M
+.B restore
+will abort with an error message. A value of 0 (the default value) disables
+the check.
+.TP
+.B \-m
+Extract by inode numbers rather than by file name. This is useful if only a few
+files are being extracted, and one wants to avoid regenerating the complete
+pathname to the file.
+.TP
+.B \-M
+Enables the multi-volume feature (for reading dumps made using the
+.B \-M
option of dump). The name specified with
-.Fl f
+.B \-f
is treated as a prefix and
-.Nm
-tries to read in sequence from <prefix>001, <prefix>002 etc.
-.It Fl N
+.B restore
+tries to read in sequence from
+.I <prefix>001, <prefix>002
+etc.
+.TP
+.B \-N
The
-.Fl N
+.B \-N
flag causes
-.Nm
+.B restore
to perform a full execution as requested by one of
-.Fl i,
-.Fl R,
-.Fl r,
-.Fl t
+.BR \-i ,
+.BR \-R ,
+.BR \-r ,
+.B t
or
-.Fl x
+.B x
command without actually writing any file on disk.
-.It Fl o
+.TP
+.B \-o
The
-.Fl o
+.B \-o
flag causes
-.Nm
-to automatically restore the current directory permissions
-without asking the operator whether to do so in one of
-.Fl i
+.B restore
+to automatically restore the current directory permissions without asking the
+operator whether to do so in one of
+.B \-i
or
-.Fl x
+.B \-x
modes.
-.It Fl Q Ar file
+.TP
+.BI \-Q " file"
Use the file
-.Ar file
-in order to read tape position as stored using the dump Quick File
-Access mode, in one of
-.Fl i,
-.Fl x
+.I file
+in order to read tape position as stored using the dump Quick File Access mode,
+in one of
+.BR \-i ,
+.B \-x
or
-.Fl t
+.B \-t
mode.
-.Pp
-It is recommended to set up the st driver to return logical tape
-positions rather than physical before calling dump/restore with
-parameter Q. Since not all tape devices support physical tape
-positions those tape devices return an error during dump/restore when
-the st driver is set to the default physical setting.
-Please see the st man page, option MTSETDRVBUFFER, or the mt man
-page, on how to set the driver to return logical tape positions.
-.Pp
-Before calling restore with parameter Q, always make sure the st
-driver is set to return the same type of tape position used during the
-call to dump. Otherwise restore may be confused.
-.Pp
-This option can be used when restoring from local or remote tapes
-(see above) or from local or remote files.
-.It Fl s Ar fileno
+.IP
+It is recommended to set up the st driver to return logical tape positions
+rather than physical before calling
+.B dump/restore
+with parameter
+.BR \-Q .
+Since not all tape devices support physical tape positions those tape devices
+return an error during
+.B dump/restore
+when the st driver is set to the default physical setting. Please see the
+.BR st (4)
+man page, option
+.B MTSETDRVBUFFER
+, or the
+.BR mt(1)
+man page, on how to set the driver to return logical tape positions.
+.IP
+Before calling
+.B restore
+with parameter
+.BR \-Q ,
+always make sure the st driver is set to return the same type of tape position
+used during the call to
+.BR dump .
+Otherwise
+.B restore
+may be confused.
+.IP
+This option can be used when restoring from local or remote tapes (see above)
+or from local or remote files.
+.TP
+.BI \-s " fileno"
Read from the specified
-.Ar fileno
-on a multi-file tape.
-File numbering starts at 1.
-.It Fl T Ar directory
+.I fileno
+on a multi-file tape. File numbering starts at 1.
+.TP
+.BI \-T " directory"
The
-.Fl T
-flag allows the user to specify a directory to use for the storage of
-temporary files. The default value is /tmp. This flag is most useful
-when restoring files after having booted from a floppy. There might be little
-or no space on the floppy filesystem, but another source of space might exist.
-.It Fl u
-When creating certain types of files, restore may generate a warning
-diagnostic if they already exist in the target directory.
-To prevent this, the
-.Fl u
-(unlink) flag causes restore to remove old entries before attempting
-to create new ones.
-.It Fl v
+.B \-T
+flag allows the user to specify a directory to use for the storage of temporary
+files. The default value is
+.IR /tmp .
+This flag is most useful when restoring files after having booted from a
+floppy. There might be little or no space on the floppy filesystem, but another
+source of space might exist.
+.TP
+.B \-u
+When creating certain types of files,
+.B restore
+may generate a warning diagnostic if they already exist in the target
+directory. To prevent this, the
+.B \-u
+(unlink) flag causes
+.B restore
+to remove old entries before attempting to create new ones.
+.TP
+.B \-v
Normally
-.Nm restore
-does its work silently.
-The
-.Fl v
-(verbose)
-flag causes it to type the name of each file it treats
-preceded by its file type.
-.It Fl V
+.B restore
+does its work silently. The
+.B \-v
+(verbose) flag causes it to type the name of each file it treats preceded by
+its file type.
+.TP
+.B \-V
Enables reading multi-volume non-tape mediums like CDROMs.
-.It Fl X Ar filelist
+.TP
+.BI \-X " filelist"
Read list of files to be listed or extracted from the text file
-.Ar filelist
+.I filelist
in addition to those specified on the command line. This can be used in
conjunction with the
-.Fl t
+.B \-t
or
-.Fl x
+.B \-x
commands. The file
-.Ar filelist
+.I filelist
should contain file names separated by newlines.
-.Ar filelist
+.I filelist
may be an ordinary file or
-.Ql Fl
+.I -
(the standard input).
-.It Fl y
+.TP
+.B \-y
Do not ask the user whether to abort the restore in the event of an error.
Always try to skip over the bad block(s) and continue.
-.El
-.Sh DIAGNOSTICS
-Complains if it gets a read error.
-If
-.Fl y
+.SH DIAGNOSTICS
+Complains if it gets a read error. If
+.B y
has been specified, or the user responds
-.Ql y ,
-.Nm restore
+.BR y ,
+.B restore
will attempt to continue the restore.
-.Pp
+.PP
If a backup was made using more than one tape volume,
-.Nm restore
-will notify the user when it is time to mount the next volume.
-If the
-.Fl x
+.B restore
+will notify the user when it is time to mount the next volume. If the
+.B \-x
or
-.Fl i
+.B \-i
flag has been specified,
-.Nm restore
-will also ask which volume the user wishes to mount.
-The fastest way to extract a few files is to
-start with the last volume, and work towards the first volume.
-.Pp
+.B restore
+will also ask which volume the user wishes to mount. The fastest way to extract
+a few files is to start with the last volume, and work towards the first volume.
+.PP
There are numerous consistency checks that can be listed by
-.Nm restore .
-Most checks are self-explanatory or can
-.Dq never happen .
-Common errors are given below.
-.Pp
-.Bl -tag -width Ds -compact
-.It Converting to new file system format
-A dump tape created from the old file system has been loaded.
-It is automatically converted to the new file system format.
-.Pp
-.It <filename>: not found on tape
-The specified file name was listed in the tape directory,
-but was not found on the tape.
-This is caused by tape read errors while looking for the file,
-and from using a dump tape created on an active file system.
-.Pp
-.It expected next file <inumber>, got <inumber>
-A file that was not listed in the directory showed up.
-This can occur when using a dump created on an active file system.
-.Pp
-.It Incremental dump too low
-When doing an incremental restore,
-a dump that was written before the previous incremental dump,
-or that has too low an incremental level has been loaded.
-.Pp
-.It Incremental dump too high
-When doing an incremental restore,
-a dump that does not begin its coverage where the previous incremental
-dump left off,
-or that has too high an incremental level has been loaded.
-.Pp
-.It Tape read error while restoring <filename>
-.It Tape read error while skipping over inode <inumber>
-.It Tape read error while trying to resynchronize
-A tape (or other media) read error has occurred.
-If a file name is specified,
-its contents are probably partially wrong.
-If an inode is being skipped or the tape is trying to resynchronize,
-no extracted files have been corrupted,
-though files may not be found on the tape.
-.Pp
-.It resync restore, skipped <num> blocks
+.BR restore .
+Most checks are self-explanatory or can \*(lqnever happen\*(rq. Common errors
+are given below:
+.TP
+.I Converting to new file system format
+A dump tape created from the old file system has been loaded. It is
+automatically converted to the new file system format.
+.TP
+.I <filename>: not found on tape
+The specified file name was listed in the tape directory, but was not found on
+the tape. This is caused by tape read errors while looking for the file, and
+from using a dump tape created on an active file system.
+.TP
+.I expected next file <inumber>, got <inumber>
+A file that was not listed in the directory showed up. This can occur when
+using a dump created on an active file system.
+.TP
+.I Incremental dump too low
+When doing an incremental restore, a dump that was written before the previous
+incremental dump, or that has too low an incremental level has been loaded.
+.TP
+.I Incremental dump too high
+When doing an incremental restore, a dump that does not begin its coverage
+where the previous incremental dump left off, or that has too high an
+incremental level has been loaded.
+.TP
+.I Tape read error while restoring <filename>
+.TP
+.I Tape read error while skipping over inode <inumber>
+.TP
+.I Tape read error while trying to resynchronize
+A tape (or other media) read error has occurred. If a file name is specified,
+its contents are probably partially wrong. If an inode is being skipped or the
+tape is trying to resynchronize, no extracted files have been corrupted, though
+files may not be found on the tape.
+.TP
+.I resync restore, skipped <num> blocks
After a dump read error,
-.Nm restore
-may have to resynchronize itself.
-This message lists the number of blocks that were skipped over.
-.El
-.Pp
-.Nm Restore
-exits with zero status on success.
-Tape errors are indicated with an exit code of 1.
-.Pp
-When doing a comparison of files from a dump, an exit code
-of 2 indicates that some files were modified or deleted since
-the dump was made.
-.Sh ENVIRONMENT
+.B restore
+may have to resynchronize itself. This message lists the number of blocks that
+were skipped over.
+.SH EXIT STATUS
+.B Restore
+exits with zero status on success. Tape errors are indicated with an exit code
+of 1.
+.PP
+When doing a comparison of files from a dump, an exit code of 2 indicates that
+some files were modified or deleted since the dump was made.
+.SH ENVIRONMENT
If the following environment variable exists it will be utilized by
-.Nm restore :
-.Pp
-.Bl -tag -width "TMPDIR" -compact
-.It Ev TAPE
-If no -f option was specified,
-.Nm
+.BR restore :
+.TP
+.B TAPE
+If no
+.B \-f
+option was specified,
+.B restore
will use the device specified via
-.Ev TAPE
+.B TAPE
as the dump device.
-.Ev TAPE
+.B TAPE
may be of the form
-.Qq tapename ,
-.Qq host:tapename
+.IR tapename ,
+.I host:tapename
or
-.Qq user@host:tapename .
-.It Ev TMPDIR
+.IR user@host:tapename .
+.TP
+.B TMPDIR
The directory given in
-.Ev TMPDIR
-will be used
-instead of
-.Pa /tmp
+.B TMPDIR
+will be used instead of
+.I /tmp
to store temporary files.
-.It Ev RMT
+.TP
+.B RMT
The environment variable
-.Ev RMT
+.B RMT
will be used to determine the pathname of the remote
-.Xr rmt 8
+.BR rmt (8)
program.
-.It Ev RSH
-.Nm Restore
-uses the contents of this variable to determine the name of the
-remote shell command to use when doing a network restore (rsh, ssh etc.).
-If this variable is not set,
-.Xr rcmd 3
+.TP
+.B RSH
+.B Restore
+uses the contents of this variable to determine the name of the remote shell
+command to use when doing a network restore (rsh, ssh etc.). If this variable
+is not set,
+.BR rcmd (3)
will be used, but only root will be able to do a network restore.
-.El
-.Sh FILES
-.Bl -tag -width "./restoresymtable" -compact
-.It Pa /dev/st0
+.SH FILES
+.TP
+.I /dev/st0
the default tape drive
-.It Pa /tmp/rstdir*
+.TP
+.I /tmp/rstdir*
file containing directories on the tape
-.It Pa /tmp/rstmode*
+.TP
+.I /tmp/rstmode*
owner, mode, and time stamps for directories
-.It Pa \&./restoresymtable
+.TP
+.I ./restoresymtable
information passed between incremental restores
-.El
-.Sh SEE ALSO
-.Xr dump 8 ,
-.Xr mount 8 ,
-.Xr mke2fs 8 ,
-.Xr rmt 8
-.Sh BUGS
-.Nm Restore
-can get confused when doing incremental restores from
-dumps that were made on active file systems.
-.Pp
-A level 0 dump must be done after a full restore.
-Because
-.Nm restore
-runs in user code,
-it has no control over inode allocation;
-thus a full dump must be done to get a new set of directories
-reflecting the new inode numbering,
-even though the content of the files is unchanged.
-.Pp
+.SH SEE ALSO
+.BR dump (8),
+.BR mount (8),
+.BR mke2fs (8),
+.BR rmt (8)
+.SH BUGS
+.B Restore
+can get confused when doing incremental restores from dumps that were made on
+active file systems.
+.PP
+A level 0 dump must be done after a full restore. Because
+.B restore
+runs in user code, it has no control over inode allocation; thus a full dump
+must be done to get a new set of directories reflecting the new inode
+numbering, even though the content of the files is unchanged.
+.PP
The temporary files
-.Pa /tmp/rstdir*
+.I /tmp/rstdir*
and
-.Pa /tmp/rstmode*
-are generated with a unique name based on the date of the dump
-and the process ID (see
-.Xr mktemp 3 ),
+.I /tmp/rstmode*
+are generated with a unique name based on the date of the dump and the process
+ID (see
+.BR mktemp (3) ),
except when
-.Fl r
+.B \-r
or
-.Fl R
-is used.
-Because
-.Fl R
+.B \-R
+is used. Because
+.B \-R
allows you to restart a
-.Fl r
-operation that may have been interrupted, the temporary files should
-be the same across different processes.
-In all other cases, the files are unique because it is possible to
-have two different dumps started at the same time, and separate
-operations shouldn't conflict with each other.
-.Pp
-To do a network restore, you have to run restore as root or use
-a remote shell replacement (see RSH variable). This is due
-to the previous security history of dump and restore. (restore is
-written to be setuid root, but we are not certain all bugs are gone
-from the restore code - run setuid at your own risk.)
-.Sh AUTHOR
+.B \-r
+operation that may have been interrupted, the temporary files should be the
+same across different processes. In all other cases, the files are unique
+because it is possible to have two different dumps started at the same time,
+and separate operations shouldn't conflict with each other.
+.PP
+To do a network restore, you have to run
+.B restore
+as root or use a remote shell replacement (see
+.B RSH
+variable). This is due to the previous security history of
+.B dump
+and
+.BR restore .
+(
+.B restore
+is written to be setuid root, but we are not certain all bugs are gone from the
+code - run setuid at your own risk.)
+.SH AUTHOR
The
-.Nm dump/restore
-backup suite was ported to Linux's Second Extended File System
-by Remy Card <card@Linux.EU.Org>. He maintained the initial versions
-of dump (up and including 0.4b4, released in january 1997).
-.Pp
-Starting with 0.4b5, the new maintainer is Stelian Pop
-.br
-<stelian@popies.net>.
-.Sh AVAILABILITY
+.B dump/restore
+backup suite was ported to Linux's Second Extended File System by Remy Card
+<card@Linux.EU.Org>. He maintained the initial versions of
+.B dump
+(up and including 0.4b4, released in january 1997).
+.PP
+Starting with 0.4b5, the new maintainer is Stelian Pop <stelian@popies.net>.
+.SH AVAILABILITY
The
-.Nm dump/restore
-backup suite is available from
-.br
-http://dump.sourceforge.net
-.Sh HISTORY
+.B dump/restore
+backup suite is available from <http://dump.sourceforge.net>
+.SH HISTORY
The
-.Nm restore
-command appeared in
-.Bx 4.2 .
+.B restore
+command appeared in 4.2BSD.
git.wh0rd.org / dump.git / blobdiff