Man pages rewrite.

diff --git a/CHANGES b/CHANGES
index efa53e8e96bebbd8622844afa1fe5b7a62660770..5747d64e5509643e5d6efe2191fb93daf5a824d2 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -1,4 +1,4 @@
-$Id: CHANGES,v 1.187 2002/07/23 12:20:35 stelian Exp $
+$Id: CHANGES,v 1.188 2002/07/24 14:11:59 stelian Exp $

 
 Changes between versions 0.4b29 and 0.4b30 (released ????????????????)
 ======================================================================
 
 Changes between versions 0.4b29 and 0.4b30 (released ????????????????)
 ======================================================================


@@ -37,6 +37,10 @@ Changes between versions 0.4b29 and 0.4b30 (released ????????????????)
        Eric S. Raymond <esr@minx.thyrsus.com> for submitting the
        patch.
 
        Eric S. Raymond <esr@minx.thyrsus.com> for submitting the
        patch.
 

+8.     Rewrote entirely the man pages using the tmac.an macro
+       package (Linux man page format) instead of the original BSD
+       format. They should be now cleaner and easier to modify.
+

 Changes between versions 0.4b28 and 0.4b29 (released June 8, 2002)
 ==================================================================
 
 Changes between versions 0.4b28 and 0.4b29 (released June 8, 2002)
 ==================================================================
 

diff --git a/dump/dump.8.in b/dump/dump.8.in
index c809558fd760587b167d59d04d551f7015665549..c92f90c3268dc512df280c3c152b2b74569efa31 100644 (file)
--- a/dump/dump.8.in
+++ b/dump/dump.8.in
@@ -30,598 +30,574 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"

-.\"    $Id: dump.8.in,v 1.43 2002/07/23 12:20:35 stelian Exp $
+.\"    $Id: dump.8.in,v 1.44 2002/07/24 14:12:00 stelian Exp $

 .\"
 .\"

-.Dd __DATE__
-.Dt DUMP 8
-.Os "dump __VERSION__"
-.Sh NAME
-.Nm dump
-.Nd ext2 filesystem backup
-.Sh SYNOPSIS
-.Nm dump
-.Op Fl 0123456789ackMnqSuv
-.Op Fl A Ar file
-.Op Fl B Ar records
-.Op Fl b Ar blocksize
-.Op Fl d Ar density
-.Op Fl e Ar inode numbers
-.Op Fl E Ar file
-.Op Fl f Ar file
-.Op Fl F Ar script
-.Op Fl h Ar level
-.Op Fl I Ar nr errors
-.Op Fl j Ar compression level
-.Op Fl L Ar label
-.Op Fl Q Ar file
-.Op Fl s Ar feet
-.Op Fl T Ar date
-.Op Fl z Ar compression level
-.Ar files-to-dump
-.Nm dump
-.Op Fl W Li \&| Fl w
-.Pp
-.in
-(The
-.Bx 4.3
-option syntax is implemented for backward compatibility but
-is not documented here.)
-.Sh DESCRIPTION
-.Nm Dump
-examines files
-on an ext2 filesystem
-and determines which files
-need to be backed up. These files
-are copied to the given disk, tape or other
-storage medium for safe keeping (see the
-.Fl f
-option below for doing remote backups).
-A dump that is larger than the output medium is broken into
-multiple volumes.
-On most media the size is determined by writing until an
-end-of-media indication is returned.
-.Pp
-On media that cannot reliably return an end-of-media indication
-(such as some cartridge tape drives), each volume is of a fixed size;
-the actual size is determined by specifying cartridge media, or via the
-tape size, density and/or block count options below.
-By default, the same output file name is used for each volume
-after prompting the operator to change media.
-.Pp
-.Ar files-to-dump
-is either a mountpoint of a filesystem
-or a list of files and directories to be backed up as a subset of a 
-filesystem.
-In the former case, either the path to a mounted filesystem
-or the device of an unmounted filesystem can be used.
-In the latter case, certain restrictions are placed on the backup:
-.Fl u
+.TH DUMP 8 "version __VERSION__ of __DATE__" BSD "System management commands"
+.SH NAME
+dump \- ext2/3 filesystem backup
+.SH SYNOPSIS
+.B dump 
+[\fB\-0123456789ackMnqSuv\fR]
+[\fB\-A \fIfile\fR]
+[\fB\-B \fIrecords\fR]
+[\fB\-b \fIblocksize\fR]
+[\fB\-d \fIdensity\fR]
+[\fB\-e \fIinode numbers\fR]
+[\fB\-E \fIfile\fR]
+[\fB\-f \fIfile\fR]
+[\fB\-F \fIscript\fR]
+[\fB\-h \fIlevel\fR]
+[\fB\-I \fInr errors\fR]
+[\fB\-j\fIcompression level\fR]
+[\fB\-L \fIlabel\fR]
+[\fB\-Q \fIfile\fR]
+[\fB\-s \fIfeet\fR]
+[\fB\-T \fIdate\fR]
+[\fB\-z\fIcompression level\fR]
+.I files-to-dump
+.PP
+.B dump 
+[\fB\-W \fR| \fB\-w\fR]
+.PP
+(The 4.3BSD option syntax is implemented for backward compatibility but is not
+documented here.)
+.SH DESCRIPTION
+.B Dump
+examines files on an ext2/3 filesystem and determines which files need to be
+backed up. These files are copied to the given disk, tape or other storage
+medium for safe keeping (see the
+.B \-f 
+option below for doing remote backups). A dump that is larger than the output 
+medium is broken into multiple volumes. On most media the size is determined by
+writing until an end-of-media indication is returned.
+.PP
+On media that cannot reliably return an end-of-media indication (such as some
+cartridge tape drives), each volume is of a fixed size; the actual size is 
+determined by specifying cartridge media, or via the tape size, density and/or
+block count options below. By default, the same output file name is used for
+each volume after prompting the operator to change media.
+.PP
+.I files-to-dump
+is either a mountpoint of a filesystem or a list of files and directories to be
+backed up as a subset of a filesystem. In the former case, either the path to a
+mounted filesystem or the device of an unmounted filesystem can be used. In the
+latter case, certain restrictions are placed on the backup:
+.B \-u

 is not allowed, the only dump level that is supported is
 is not allowed, the only dump level that is supported is

-.Fl 0 
+.B 0 

 and all the files and directories must reside on the same filesystem.
 and all the files and directories must reside on the same filesystem.

-.Pp
+.SH OPTIONS

 The following options are supported by
 The following options are supported by

-.Nm Ns :
-.Bl -tag -width Ds
-.It Fl 0\-9
-Dump levels.
-A level 0, full backup,
-guarantees the entire file system is copied
-(but see also the
-.Fl h
-option below).
-A level number above 0,
-incremental backup,
-tells
-.Nm dump
+.B dump:
+.TP
+.BI \-0\-9
+Dump levels. A level 0, full backup, guarantees the entire file system is
+copied (but see also the
+.B \-h
+option below). A level number above 0, incremental backup, tells
+.B dump

 to
 to

-copy all files new or modified since the
-last dump of a lower level.
-The default level is 9.
-.It Fl a
-.Dq auto-size .
-Bypass all tape length calculations, and write
-until an end-of-media indication is returned.  This works best
-for most modern tape drives, and is the default.  
-Use of this option is particularly recommended when appending to an 
-existing tape, or using a tape drive with hardware compression 
+copy all files new or modified since the last dump of a lower level. The 
+default level is 9.
+.TP
+.BI \-a 
+\*(lqauto-size\*(rq. Bypass all tape length calculations, and write until an 
+end-of-media indication is returned.  This works best for most modern tape
+drives, and is the default. Use of this option is particularly recommended when
+appending to an existing tape, or using a tape drive with hardware compression 

 (where you can never be sure about the compression ratio).
 (where you can never be sure about the compression ratio).

-.It Fl A Ar archive_file
-Archive a dump table-of-contents in the
-specified
-.Ar archive_file
+.TP
+.BI \-A " archive_file"
+Archive a dump table-of-contents in the specified
+.I archive_file

 to be used by 
 to be used by 

-.Xr restore 8
+.BR restore (8)

 to determine whether a file is in the dump file that is being restored.
 to determine whether a file is in the dump file that is being restored.

-.It Fl b Ar blocksize
-The number of kilobytes per dump record.
-Since the IO system slices all requests into chunks of MAXBSIZE
-(typically 64kB), it is not possible to use a larger blocksize
-without having problems later with
-.Xr restore 8 .
+.TP
+.BI \-b " blocksize"
+The number of kilobytes per dump record. Since the IO system slices all
+requests into chunks of 
+.B MAXBSIZE
+(typically 64kB), it is not possible to use a larger blocksize without having 
+problems later with
+.BR restore (8).

 Therefore
 Therefore

-.Nm dump
-will constrain writes to MAXBSIZE.
+.B dump
+will constrain writes to 
+.B MAXBSIZE.

 The default blocksize is 10.
 The default blocksize is 10.

-.It Fl B Ar records
+.TP
+.BI \-B " records"

 The number of 1 kB blocks per volume. Not normally required, as
 The number of 1 kB blocks per volume. Not normally required, as

-.Nm
+.B dump

 can detect end-of-media. When the specified size is reached,
 can detect end-of-media. When the specified size is reached,

-.Nm
-waits for you to change the volume.  This option overrides
-the calculation of tape size based on length and density.
-If compression is on this limits the size of the compressed
-output per volume.
-.It Fl c
-Change the defaults for use with a cartridge tape drive, with a density
-of 8000 bpi, and a length of 1700 feet. Specifying a cartridge drive
-overrides the end-of-media detection.
-.It Fl d Ar density
-Set tape density to
-.Ar density .
-The default is 1600BPI. Specifying a tape density overrides the 
+.B dump
+waits for you to change the volume.  This option overrides the calculation of 
+tape size based on length and density. If compression is on this limits the 
+size of the compressed output per volume.
+.TP
+.BI \-c
+Change the defaults for use with a cartridge tape drive, with a density of 8000
+bpi, and a length of 1700 feet. Specifying a cartridge drive overrides the

 end-of-media detection.
 end-of-media detection.

-.It Fl e Ar inodes
+.TP
+.BI \-d " density"
+Set tape density to
+.IR density .
+The default is 1600BPI. Specifying a tape density overrides the end-of-media
+detection.
+.TP
+.BI \-e " inodes"

 Exclude 
 Exclude 

-.Ar inodes
+.I inodes

 from the dump. The
 from the dump. The

-.Ar inodes
+.I inodes

 parameter is a comma separated list of inode numbers (you can use
 parameter is a comma separated list of inode numbers (you can use

-.Ar stat 
+.BR stat (1)

 to find the inode number for a file or directory).
 to find the inode number for a file or directory).

-.It Fl E Ar file
+.TP
+.BI \-E " file"

 Read list of inodes to be excluded from the dump from the text file
 Read list of inodes to be excluded from the dump from the text file

-.Ar file .
+.IR file .

 The file 
 The file 

-.Ar file
-should be an ordinary file containing inode numbers separated by
-newlines.
-.It Fl f Ar file
+.I file
+should be an ordinary file containing inode numbers separated by newlines.
+.TP
+.BI \-f " file"

 Write the backup to
 Write the backup to

-.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),
 (a tape drive),

-.Pa /dev/rsd1c
-(a floppy disk drive),
-an ordinary file,
+.I /dev/rsd1c
+(a floppy disk drive), an ordinary file, or
+.I \-
+(the standard output). Multiple file names may be given as a single argument
+separated by commas. Each file will be used for one dump volume in the order
+listed; if the dump requires more volumes than the number of names given,
+the last file name will used for all remaining volumes after prompting for
+media changes. If the name of the file is of the form
+.I host:file

 or
 or

-.Ql Fl
-(the standard output).
-Multiple file names may be given as a single argument separated by commas.
-Each file will be used for one dump volume in the order listed;
-if the dump requires more volumes than the number of names given,
-the last file name will used for all remaining volumes after prompting
-for media changes.
-If the name of the file is of the form
-.Dq host:file
-or
-.Dq user@host:file
-.Nm
+.I user@host:file
+.B dump

 writes to the named file on the remote host using
 writes to the named file on the remote host using

-.Xr rmt 8 .
+.BR rmt (8).

 The default path name of the remote
 The default path name of the remote

-.Xr rmt 8
+.BR rmt (8)

 program is
 program is

-.\" rmt path, is the path on the remote host
-.Pa /etc/rmt ;
+.IR /etc/rmt ;

 this can be overridden by the environment variable
 this can be overridden by the environment variable

-.Ev RMT .
-.It Fl F Ar script
-Run script at the end 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 .
+.TP
+.BI \-F " script"
+Run script at the end of each tape. The device name and the current volume
+number are passed on the command line. The script must return 0 if 
+.B dump

 should continue without asking the user to change the tape, 1 if 
 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 Ar level
+.B dump
+should continue but ask the user to change the tape. Any other exit code will 
+cause
+.B dump
+to abort. For security reasons,
+.B dump
+reverts back to the real user ID and the real group ID before running the
+script.
+.TP
+.BI \-h " level"

 Honor the user
 Honor the user

-.Dq nodump
+.B nodump

 flag
 flag

-.Dv UF_NODUMP
+.B UF_NODUMP

 only for dumps at or above the given
 only for dumps at or above the given

-.Ar level .
-The default honor level is 1,
-so that incremental backups omit such files
-but full backups retain them.
-.It Fl I Ar nr errors
+.IR level .
+The default honor level is 1, so that incremental backups omit such files but
+full backups retain them.
+.TP
+.BI \-I " nr errors"

 By default,
 By default,

-.Nm
-will ignore the first 32 read errors on the file
-system before asking for operator intervention. You can change this
-using this flag to any value. This is useful when running
-.Nm
-on an active filesystem where read errors simply indicate an
-inconsistency between the mapping and dumping passes.
-.It Fl j Ar compression level
-Compress every block to be written on the tape using bzlib library. This
-option will work only when dumping to a file or pipe or, when dumping
-to a tape drive, if the tape drive is capable of writing variable 
-length blocks. You will need at least the 0.4b24 version of restore in 
-order to extract compressed tapes. Tapes written using compression will
-not be compatible with the BSD tape format. The (optional) parameter 
-specifies the compression level bzlib will use. The default compression
-level is 2. If the optional parameter is specified, there should be no 
-white space between the option letter and the parameter.
-.It Fl k
-Use Kerberos authentication to talk to remote tape servers.  (Only
-available if this option was enabled when
-.Nm
+.B dump
+will ignore the first 32 read errors on the file system before asking for 
+operator intervention. You can change this using this flag to any value. This 
+is useful when running
+.B dump
+on an active filesystem where read errors simply indicate an inconsistency 
+between the mapping and dumping passes.
+.TP
+.BI \-j "compression level"
+Compress every block to be written on the tape using bzlib library. This option
+will work only when dumping to a file or pipe or, when dumping to a tape drive,
+if the tape drive is capable of writing variable length blocks. You will need
+at least the 0.4b24 version of 
+.B restore
+in order to extract compressed tapes. Tapes written using compression will not
+be compatible with the BSD tape format. The (optional) parameter specifies the 
+compression level bzlib will use. The default compression level is 2. If the
+optional parameter is specified, there should be no white space between the 
+option letter and the parameter.
+.TP
+.BI \-k
+Use Kerberos authentication to talk to remote tape servers. (Only available if
+this option was enabled when
+.B dump

 was compiled.)
 was compiled.)

-.It Fl L Ar label
+.TP
+.BI \-L " label"

 The user-supplied text string
 The user-supplied text string

-.Ar label
+.I label

 is placed into the dump header, where tools like
 is placed into the dump header, where tools like

-.Xr restore 8
+.BR restore (8)

 and
 and

-.Xr file 1
-can access it.
-Note that this label is limited
-to be at most LBLSIZE (currently 16) characters, which must include
-the terminating
-.Ql \e0 .
-.It Fl m
+.BR file (8)
+can access it. Note that this label is limited to be at most 
+.B LBLSIZE
+(currently 16) characters, which must include the terminating \e0.
+.TP
+.BI \-m

 If this flag is specified,
 If this flag is specified,

-.Nm
-will optimise the output for inodes having been changed but not
-modified since the last dump ('changed' and 'modified' have the
-meaning defined in stat(2)). For those inodes,
-.Nm
-will save only the metadata, instead of saving the entire inode 
-contents. Inodes which are either directories or have been modified
-since the last dump are saved in a regular way.
-Uses of this flag must be consistent, meaning that either every dump 
-in an incremental dump set have the flag, or no one has it.
-.Pp
-Tapes written using such 'metadata only' inodes will not be compatible
-with the BSD tape format or older versions of
-.Nm restore.
-.It Fl M
+.B dump
+will optimise the output for inodes having been changed but not modified since 
+the last dump ('changed' and 'modified' have the meaning defined in
+.BR stat (2)
+). For those inodes,
+.B dump
+will save only the metadata, instead of saving the entire inode contents. 
+Inodes which are either directories or have been modified since the last dump 
+are saved in a regular way. Uses of this flag must be consistent, meaning that
+either every dump in an incremental dump set have the flag, or no one has it.
+.IP
+Tapes written using such 'metadata only' inodes will not be compatible with the
+BSD tape format or older versions of
+.B restore.
+.TP
+.BI \-M

 Enable the multi-volume feature. The name specified with 
 Enable the multi-volume feature. The name specified with 

-.Fl f 
+.B f 

 is treated as a prefix and 
 is treated as a prefix and 

-.Nm
-writes in sequence to <prefix>001, <prefix>002 etc. This can be
-useful when dumping to files on an ext2 partition, in order to bypass
-the 2GB file size limitation.
-.It Fl n
+.B dump
+writes in sequence to
+.I <prefix>001, <prefix>002 
+etc. This can be useful when dumping to files on an ext2 partition, in order to
+bypass the 2GB file size limitation.
+.TP
+.BI \-n

 Whenever
 Whenever

-.Nm
-requires operator attention,
-notify all operators in the group
-.Dq operator
+.B dump
+requires operator attention, notify all operators in the group
+.B operator

 by means similar to a
 by means similar to a

-.Xr wall 1 .
-.It Fl q
+.BR wall (1).
+.TP
+.BI \-q

 Make
 Make

-.Nm
-abort immediately whenever operator attention is required,
-without prompting in case of write errors, tape changes etc.
-.It Fl Q Ar file
-Enable the Quick File Access support. Tape positions for each
-inode are stored into the file
-.Ar file
-which is used by restore (if called with parameter Q and the filename)
-to directly position the tape at the file restore is currently working
-on.  This saves hours when restoring single files from large backups,
-saves the tapes and the drive's head.
-.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 dumping to local tapes (see above)
-or to local files.
-.It Fl s Ar feet
-Attempt to calculate the amount of tape needed at a particular density.
-If this amount is exceeded,
-.Nm
-prompts for a new tape.
-It is recommended to be a bit conservative on this option.
-The default tape length is 2300 feet. Specifying the tape size 
+.B dump
+abort immediately whenever operator attention is required, without prompting in
+case of write errors, tape changes etc.
+.TP
+.BI \-Q " file"
+Enable the Quick File Access support. Tape positions for each inode are stored 
+into the file
+.I file
+which is used by 
+.B restore
+(if called with parameter 
+.B \-Q
+and the filename) to directly position the tape at the file 
+.B restore 
+is currently working on. This saves hours when restoring single files from
+large backups, saves the tapes and the drive's head.
+.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 dumping to local tapes (see above) or to local 
+files.
+.TP
+.BI \-s " feet"
+Attempt to calculate the amount of tape needed at a particular density. If this
+amount is exceeded,
+.B dump
+prompts for a new tape. It is recommended to be a bit conservative on this 
+option. The default tape length is 2300 feet. Specifying the tape size 

 overrides end-of-media detection.
 overrides end-of-media detection.

-.ne 1i
-.It Fl S
-Size estimate. Determine the amount of space
-that is needed to perform the dump without
-actually doing it, and display the estimated
-number of bytes it will take. This is useful
-with incremental dumps to determine how many
-volumes of media will be needed.
-.It Fl T Ar date
-Use the specified date as the starting time for the dump
-instead of the time determined from looking in
-.Pa __DUMPDATES__ .
+.TP
+.BI \-S
+Size estimate. Determine the amount of space that is needed to perform the dump
+without actually doing it, and display the estimated number of bytes it will
+take. This is useful with incremental dumps to determine how many volumes of
+media will be needed.
+.TP
+.BI \-T " date"
+Use the specified date as the starting time for the dump instead of the time 
+determined from looking in
+.I __DUMPDATES__ .

 The format of
 The format of

-.Ar date
+.I date

 is the same as that of
 is the same as that of

-.Xr ctime 3 .
-This option is useful for automated dump scripts that wish to
-dump over a specific period of time.
-The
-.Fl T
+.BR ctime (3).
+This option is useful for automated dump scripts that wish to dump over a 
+specific period of time. The
+.B \-T

 option is mutually exclusive from the
 option is mutually exclusive from the

-.Fl u
+.B \-u

 option.
 option.

-.It Fl u
+.TP
+.BI \-u

 Update the file
 Update the file

-.Pa __DUMPDATES__
-after a successful dump.
-The format of
-.Pa __DUMPDATES__
-is readable by people, consisting of one
-free format record per line:
-filesystem name,
-increment level
-and
-.Xr ctime 3
-format dump date. 
-There may be only one entry per filesystem at each level.
-The file
-.Pa __DUMPDATES__
-may be edited to change any of the fields,
-if necessary.
-.It Fl v
+.I __DUMPDATES__
+after a successful dump. The format of
+.I __DUMPDATES__
+is readable by people, consisting of one free format record per line:
+filesystem name, increment level and
+.BR ctime (3)
+format dump date. There may be only one entry per filesystem at each level. The
+file
+.I __DUMPDATES__
+may be edited to change any of the fields, if necessary.
+.TP
+.BI \-v

 The
 The

-.Fl v
+.B \-v

 (verbose) makes
 (verbose) makes

-.Nm dump
+.B dump

 to print extra information which could be helpful in debug sessions.
 to print extra information which could be helpful in debug sessions.

-.It Fl W
-.Nm Dump
-tells the operator what file systems need to be dumped.
-This information is gleaned from the files
-.Pa __DUMPDATES__
+.TP
+.BI \-W
+.B Dump
+tells the operator what file systems need to be dumped. This information is
+gleaned from the files
+.I __DUMPDATES__

 and
 and

-.Pa /etc/fstab .
+.IR /etc/fstab .

 The
 The

-.Fl W
+.B \-W

 option causes
 option causes

-.Nm
+.B dump

 to print out, for all file systems in
 to print out, for all file systems in

-.Pa __DUMPDATES__ ,
+.I __DUMPDATES__ ,

 and regognized file systems in
 and regognized file systems in

-.Pa /etc/fstab .
-the most recent dump date and level,
-and highlights those that should be dumped.
-If the
-.Fl W
+.IR /etc/fstab .
+the most recent dump date and level, and highlights those that should be 
+dumped. If the
+.B \-W

 option is set, all other options are ignored, and
 option is set, all other options are ignored, and

-.Nm
+.B dump

 exits immediately.
 exits immediately.

-.It Fl w
+.TP 
+.BI \-w

 Is like
 Is like

-.Fl W ,
+.BR \-W ,

 but prints only recognized filesystems in
 but prints only recognized filesystems in

-.Pa /etc/fstab
+.I /etc/fstab

 which need to be dumped.
 which need to be dumped.

-.It Fl z Ar compression level
-Compress every block to be written on the tape using zlib library. This
-option will work only when dumping to a file or pipe or, when dumping
-to a tape drive, if the tape drive is capable of writing variable 
-length blocks. You will need at least the 0.4b22 version of restore in 
-order to extract compressed tapes. Tapes written using compression will
-not be compatible with the BSD tape format. The (optional) parameter 
-specifies the compression level zlib will use. The default compression
-level is 2. If the optional parameter is specified, there should be no 
-white space between the option letter and the parameter.
-.El
-.Pp
-.Nm Dump
-requires operator intervention on these conditions:
-end of tape,
-end of dump,
-tape write error,
-tape open error or
-disk read error (if there is more than a threshold of nr errors).
-In addition to alerting all operators implied by the
-.Fl n
+.TP
+.BI \-z "compression level"
+Compress every block to be written on the tape using zlib library. This option
+will work only when dumping to a file or pipe or, when dumping to a tape drive,
+if the tape drive is capable of writing variable length blocks. You will need 
+at least the 0.4b22 version of
+.B restore
+in order to extract compressed tapes. Tapes written using compression will not
+be compatible with the BSD tape format. The (optional) parameter specifies the
+compression level zlib will use. The default compression level is 2. If the
+optional parameter is specified, there should be no white space between the 
+option letter and the parameter.
+.PP
+.B Dump
+requires operator intervention on these conditions: end of tape, end of dump,
+tape write error, tape open error or disk read error (if there is more than a 
+threshold of nr errors). In addition to alerting all operators implied by the
+.B \-n

 key,
 key,

-.Nm
-interacts with the operator on
-.Em dump's
-control terminal at times when
-.Nm
-can no longer proceed,
-or if something is grossly wrong.
-All questions
-.Nm
+.B dump
+interacts with the operator on dump's control terminal at times when
+.B dump
+can no longer proceed, or if something is grossly wrong. All questions
+.B dump

 poses
 poses

-.Em must
-be answered by typing
-.Dq yes
-or
-.Dq no ,
-appropriately.
-.Pp
+.I must
+be answered by typing \*(lqyes\*(rq or \*(lqno\*(rq, appropriately.
+.PP

 Since making a dump involves a lot of time and effort for full dumps,
 Since making a dump involves a lot of time and effort for full dumps,

-.Nm
-checkpoints itself at the start of each tape volume.
-If writing that volume fails for some reason,
-.Nm
-will,
-with operator permission,
-restart itself from the checkpoint
-after the old tape has been rewound and removed,
-and a new tape has been mounted.
-.Pp
-.Nm Dump
-tells the operator what is going on at periodic intervals,
-including usually low estimates of the number of blocks to write,
-the number of tapes it will take, the time to completion, and
-the time to the tape change.
-The output is verbose,
-so that others know that the terminal
-controlling
-.Nm
-is busy,
-and will be for some time.
-.Pp
-In the event of a catastrophic disk event, the time required
-to restore all the necessary backup tapes or files to disk
-can be kept to a minimum by staggering the incremental dumps.
-An efficient method of staggering incremental dumps
-to minimize the number of tapes follows:
-.Bl -bullet -offset indent
-.It
+.B dump
+checkpoints itself at the start of each tape volume. If writing that volume
+fails for some reason,
+.B dump
+will, with operator permission, restart itself from the checkpoint after the
+old tape has been rewound and removed, and a new tape has been mounted.
+.PP
+.B Dump
+tells the operator what is going on at periodic intervals, including usually 
+low estimates of the number of blocks to write, the number of tapes it will
+take, the time to completion, and the time to the tape change. The output is
+verbose, so that others know that the terminal controlling
+.B dump
+is busy, and will be for some time.
+.PP
+In the event of a catastrophic disk event, the time required to restore all the
+necessary backup tapes or files to disk can be kept to a minimum by staggering 
+the incremental dumps. An efficient method of staggering incremental dumps to
+minimize the number of tapes follows:
+.IP \(em

 Always start with a level 0 backup, for example:
 Always start with a level 0 backup, for example:

-.Bd -literal -offset indent
-/sbin/dump -0u -f /dev/st0 /usr/src
-.Ed
-.Pp
+.RS 14
+.B /sbin/dump -0u -f /dev/st0 /usr/src
+.RE
+.IP

 This should be done at set intervals, say once a month or once every two months,
 and on a set of fresh tapes that is saved forever.
 This should be done at set intervals, say once a month or once every two months,
 and on a set of fresh tapes that is saved forever.

-.It
-After a level 0, dumps of active file
-systems are taken on a daily basis,
-using a modified Tower of Hanoi algorithm,
-with this sequence of dump levels:
-.Bd -literal -offset indent
-3 2 5 4 7 6 9 8 9 9 ...
-.Ed
-.Pp
-For the daily dumps, it should be possible to use a fixed number of tapes
-for each day, used on a weekly basis.
-Each week, a level 1 dump is taken, and
-the daily Hanoi sequence repeats beginning with 3.
-For weekly dumps, another fixed set of tapes per dumped file system is
-used, also on a cyclical basis.
-.El
-.Pp
-After several months or so, the daily and weekly tapes should get
-rotated out of the dump cycle and fresh tapes brought in.
-.Sh ENVIRONMENT
-.Bl -tag -width Fl
-.It Ev TAPE
-If no -f option was specified,
-.Nm
+.IP \(em
+After a level 0, dumps of active file systems are taken on a daily basis, using
+a modified Tower of Hanoi algorithm, with this sequence of dump levels:
+.RS 14
+.B 3 2 5 4 7 6 9 8 9 9 ...
+.RE
+.IP
+For the daily dumps, it should be possible to use a fixed number of tapes for
+each day, used on a weekly basis. Each week, a level 1 dump is taken, and the
+daily Hanoi sequence repeats beginning with 3. For weekly dumps, another fixed 
+set of tapes per dumped file system is used, also on a cyclical basis.
+.PP
+After several months or so, the daily and weekly tapes should get rotated out
+of the dump cycle and fresh tapes brought in.
+.SH ENVIRONMENT
+.TP 
+.B TAPE
+If no 
+.B \-f 
+option was specified,
+.B dump

 will use the device specified via
 will use the device specified via

-.Ev TAPE
+.B TAPE

 as the dump device.
 as the dump device.

-.Ev TAPE
+.B TAPE

 may be of the form
 may be of the form

-.Qq tapename ,
-.Qq host:tapename ,
+.IR tapename ,
+.IR host:tapename ,

 or
 or

-.Qq user@host:tapename .
-.It Ev RMT
+.IR user@host:tapename .
+.TP
+.B RMT

 The environment variable
 The environment variable

-.Ev RMT
+.B RMT

 will be used to determine the pathname of the remote
 will be used to determine the pathname of the remote

-.Xr rmt 8
+.BR rmt (8)

 program.
 program.

-.It Ev RSH
-.Nm Dump
-uses the contents of this variable to determine the name of the
-remote shell command to use when doing remote backups (rsh, ssh etc.). 
-If this variable is not set, 
-.Xr rcmd 3
+.TP
+.B RSH
+.B Dump
+uses the contents of this variable to determine the name of the remote shell
+command to use when doing remote backups (rsh, ssh etc.). If this variable is
+not set, 
+.BR rcmd (3)

 will be used, but only root will be able to do remote backups.
 will be used, but only root will be able to do remote backups.

-.El
-.Sh FILES
-.Bl -tag -width __DUMPDATES__ -compact
-.It Pa /dev/st0
+.SH FILES
+.TP
+.I /dev/st0

 default tape unit to dump to
 default tape unit to dump to

-.It Pa __DUMPDATES__
+.TP
+.I __DUMPDATES__

 dump date records
 dump date records

-.It Pa /etc/fstab
+.TP
+.I /etc/fstab

 dump table: file systems and frequency
 dump table: file systems and frequency

-.It Pa /etc/group
+.TP
+.I /etc/group

 to find group
 to find group

-.Em operator
-.El
-.Sh SEE ALSO
-.Xr fstab 5 ,
-.Xr restore 8 ,
-.Xr rmt 8
-.Sh DIAGNOSTICS
+.I operator
+.SH SEE ALSO
+.BR fstab (5),
+.BR restore (8),
+.BR rmt (8)
+.SH DIAGNOSTICS

 Many, and verbose.
 Many, and verbose.

-.Pp
-.Nm Dump
-exits with zero status on success.
-Startup errors are indicated with an exit code of 1;
-abnormal termination is indicated with an exit code of 3.
-.Sh BUGS
-It might be considered a bug that this version of dump can only handle ext2
+.SH EXIT STATUS
+.B Dump
+exits with zero status on success. Startup errors are indicated with an exit
+code of 1; abnormal termination is indicated with an exit code of 3.
+.SH BUGS
+It might be considered a bug that this version of dump can only handle ext2/3

 filesystems.  Specifically, it does not work with FAT filesystems.
 filesystems.  Specifically, it does not work with FAT filesystems.

-.Pp
-Fewer than 32 read errors (change this with -I)
-on the filesystem are ignored. If noticing
-read errors is important, the output from dump can be parsed to look for lines
-that contain the text 'read error'.
-.Pp
+.PP
+Fewer than 32 read errors (change this with 
+.BR \-I )
+on the filesystem are ignored. If noticing read errors is important, the output
+from dump can be parsed to look for lines that contain the text 'read error'.
+.PP

 When a read error occurs,
 When a read error occurs,

-.Nm
+.B dump

 prints out the corresponding physical disk block and sector number and the
 prints out the corresponding physical disk block and sector number and the

-ext2 logical block number.
-It doesn't print out the corresponing file name or even the inode number. 
-The user has to use 
-.Xr debugfs 8 ,
+ext2/3 logical block number. It doesn't print out the corresponing file name or
+even the inode number. The user has to use 
+.BR debugfs (8),

 commands
 commands

-.Pa ncheck
+.B ncheck

 and
 and

-.Pa icheck
+.B icheck

 to translate the
 to translate the

-.Pa ext2blk
-number printed out by dump into an inode number, then into a file name.
-.Pp
-Each reel requires a new process, so parent processes for
-reels already written just hang around until the entire tape
-is written.
-.Pp
+.B ext2blk
+number printed out by 
+.B dump
+into an inode number, then into a file name.
+.PP
+Each reel requires a new process, so parent processes for reels already written
+just hang around until the entire tape is written.
+.PP

 The estimated number of tapes is not correct if compression is on.
 The estimated number of tapes is not correct if compression is on.

-.Pp
+.PP

 It would be nice if
 It would be nice if

-.Nm
-knew about the dump sequence,
-kept track of the tapes scribbled on,
-told the operator which tape to mount when,
-and provided more assistance
-for the operator running
-.Xr restore .
-.Pp
-.Nm Dump
-cannot do remote backups without being run as root, due to its
-security history.
-Presently, it works if you set it setuid (like it used to be), but this
-might constitute a security risk. Note that you can set RSH to use
-a remote shell program instead.
-.Sh AUTHOR
+.B dump
+knew about the dump sequence, kept track of the tapes scribbled on, told the
+operator which tape to mount when, and provided more assistance for the 
+operator running
+.BR restore .
+.PP
+.B Dump
+cannot do remote backups without being run as root, due to its security history.
+Presently, it works if you set it setuid (like it used to be), but this might
+constitute a security risk. Note that you can set 
+.B RSH
+to use a remote shell program instead.
+.SH AUTHOR

 The 
 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
 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

 A
 A

-.Nm
+.B dump

 command appeared in
 command appeared in

-.At v6 .
+.B Version 6 AT&T UNIX.

diff --git a/restore/restore.8.in b/restore/restore.8.in
index 4dbaeceba563c35e06a53a4e664deb8a683760f4..92544bf56accb1876442ad2c4246523e082247ec 100644 (file)
--- a/restore/restore.8.in
+++ b/restore/restore.8.in
@@ -29,721 +29,705 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
 .\" 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
 The

-.Nm restore
+.B restore

 command performs the inverse function of
 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.
 the files and (recursively) subdirectories of that directory.

-.Pp
+.PP

 Exactly one of the following flags is required:
 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.
 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.
 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.
 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.
 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.
 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 
 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.
 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 
 creates a new Quick File Access file 

-.Ar file
+.I file

 from an existing dump file without restoring its contents.
 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
 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 
 Note that 

-.Nm restore
+.B restore

 leaves a file 
 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
 in conjunction with

-.Xr mke2fs 8
+.BR mke2fs (8)

 and
 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
 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.
 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.
 option below.

-.El
-.Pp
+.SH OPTIONS

 The following additional options may be specified:
 The following additional options may be specified:

-.Bl -tag -width Ds
-.It Fl a
+.TP
+.B \-a

 In 
 In 

-.Fl i
+.B \-i

 or
 or

-.Fl x
+.B \-x

 mode, 
 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
 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 
 instead of the media. This option can be used in combination with the 

-.Fl t, 
-.Fl i, 
+.BR \-t ,
+.BR \-i ,

 or 
 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,
 option is not specified,

-.Nm restore
+.B restore

 tries to determine the media block size dynamically.
 tries to determine the media block size dynamically.

-.It Fl c
+.TP
+.B \-c

 Normally,
 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
 The

-.Fl d
-(debug)
-flag causes
-.Nm restore
+.B \-d
+(debug) flag causes
+.B restore

 to print debug information.
 to print debug information.

-.It Fl D Ar filesystem
+.TP
+.BI \-D " filesystem"

 The
 The

-.Fl D
+.B \-D

 flag allows the user to specify the filesystem name when using
 flag allows the user to specify the filesystem name when using

-.Nm restore
+.B restore

 with the
 with the

-.Fl C
+.B \-C

 option to check the backup.
 option to check the backup.

-.It Fl f Ar file
+.TP
+.BI \-f " file"

 Read the backup from
 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),
 (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
 or

-.Dq user@host:file ,
-.Nm restore
+.IR user@host:file ,
+.B restore

 reads from the named file on the remote host using
 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 
 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.)
 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.
 will fail to access it correctly.

-.It Fl L Ar limit
+.TP
+.BI \-L " limit"

 The
 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
 with the

-.Fl C
+.B \-C

 option to check the backup. If this limit is reached, 
 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
 option of dump). The name specified with

-.Fl f
+.B \-f

 is treated as a prefix and
 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
 The

-.Fl N
+.B \-N

 flag causes
 flag causes

-.Nm
+.B restore

 to perform a full execution as requested by one of
 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
 or

-.Fl x
+.B x

 command without actually writing any file on disk.
 command without actually writing any file on disk.

-.It Fl o
+.TP
+.B \-o

 The
 The

-.Fl o
+.B \-o

 flag causes
 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
 or

-.Fl x
+.B \-x

 modes.
 modes.

-.It Fl Q Ar file
+.TP
+.BI \-Q " file"

 Use the 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
 or

-.Fl t
+.B \-t

 mode.
 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
 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
 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
 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.
 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
 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
 in addition to those specified on the command line. This can be used in 
 conjunction with the

-.Fl t
+.B \-t

 or
 or

-.Fl x
+.B \-x

 commands. The file
 commands. The file

-.Ar filelist
+.I filelist

 should contain file names separated by newlines.
 should contain file names separated by newlines.

-.Ar filelist
+.I filelist

 may be an ordinary file or
 may be an ordinary file or

-.Ql Fl
+.I -

 (the standard input).
 (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.
 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
 has been specified, or the user responds

-.Ql y ,
-.Nm restore
+.BR y ,
+.B restore

 will attempt to continue the restore.
 will attempt to continue the restore.

-.Pp
+.PP

 If a backup was made using more than one tape volume,
 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
 or

-.Fl i
+.B \-i

 flag has been specified,
 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
 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, 
 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
 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
 will use the device specified via

-.Ev TAPE
+.B TAPE

 as the dump device.
 as the dump device.

-.Ev TAPE
+.B TAPE

 may be of the form
 may be of the form

-.Qq tapename ,
-.Qq host:tapename
+.IR tapename ,
+.I host:tapename

 or
 or

-.Qq user@host:tapename .
-.It Ev TMPDIR
+.IR user@host:tapename .
+.TP
+.B TMPDIR

 The directory given in
 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.
 to store temporary files.

-.It Ev RMT
+.TP
+.B RMT

 The environment variable
 The environment variable

-.Ev RMT
+.B RMT

 will be used to determine the pathname of the remote
 will be used to determine the pathname of the remote

-.Xr rmt 8
+.BR rmt (8)

 program.
 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.
 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
 the default tape drive

-.It Pa /tmp/rstdir*
+.TP
+.I /tmp/rstdir*

 file containing directories on the tape
 file containing directories on the tape

-.It Pa /tmp/rstmode*
+.TP
+.I /tmp/rstmode*

 owner, mode, and time stamps for directories
 owner, mode, and time stamps for directories

-.It Pa \&./restoresymtable
+.TP
+.I ./restoresymtable

 information passed between incremental restores
 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
 The temporary files

-.Pa /tmp/rstdir*
+.I /tmp/rstdir*

 and
 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
 except when

-.Fl r
+.B \-r

 or
 or

-.Fl R
-is used.
-Because
-.Fl R
+.B \-R
+is used. Because
+.B \-R

 allows you to restart a
 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
 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
 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
 The

-.Nm restore
-command appeared in
-.Bx 4.2 .
+.B restore
+command appeared in 4.2BSD.

diff --git a/rmt/rmt.8.in b/rmt/rmt.8.in
index 6e93213178e2fcbce436b84b5d24eba618757e4b..228d2b24979c84c17f64e83b74a6d3ae7fe5f182 100644 (file)
--- a/rmt/rmt.8.in
+++ b/rmt/rmt.8.in
@@ -29,339 +29,341 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"

-.\"     $Id: rmt.8.in,v 1.8 2002/04/15 11:57:29 stelian Exp $
+.\"     $Id: rmt.8.in,v 1.9 2002/07/24 14:12:01 stelian Exp $

 .\"
 .\"

-.Dd __DATE__
-.Dt RMT 8
-.Os "rmt __VERSION__"
-.Sh NAME
-.Nm rmt
-.Nd remote magtape protocol module
-.Sh SYNOPSIS
-.Nm rmt
-.Sh DESCRIPTION
-.Nm rmt
+.TH RMT 8 "version __VERSION__ of __DATE__" BSD "System management commands"
+.SH NAME
+rmt \- remote magtape protocol module
+.SH SYNOPSIS
+.B rmt
+.SH DESCRIPTION
+.B Rmt

 is a program used by the remote 
 is a program used by the remote 

-.Nm dump,
-.Nm restore 
+.BR dump (8),
+.BR restore (8)

 or
 or

-.Nm tar
+.BR tar (1)

 programs in manipulating a magnetic tape drive through an interprocess
 communication connection.
 programs in manipulating a magnetic tape drive through an interprocess
 communication connection.

-.Nm rmt
+.B Rmt

 is normally started up with an
 is normally started up with an

-.Xr rexec 3
+.BR rexec (3)

 or
 or

-.Xr rcmd 3
+.BR rcmd (3)

 call.
 call.

-.Pp
+.PP

 The 
 The 

-.Nm
+.B rmt

 program accepts requests specific to the manipulation of magnetic tapes, 
 program accepts requests specific to the manipulation of magnetic tapes, 

-performs the commands, then responds with a status indication.  
-All responses are in
-.Tn ASCII
+performs the commands, then responds with a status indication.  All responses 
+are in
+.B ASCII

 and in one of the following two forms.
 and in one of the following two forms.

-.Pp
+.PP

 Successful commands have responses of:
 Successful commands have responses of:

-.Bd -filled -offset indent
-.Sm off
-.Sy A Ar number No \en
-.Sm on
-.Ed
-.Pp
+.RS
+.B A\fInumber\fR\en
+.RE
+.PP

 where
 where

-.Ar number
+.I number

 is an
 is an

-.Tn ASCII
+.B ASCII

 representation of a decimal number.
 representation of a decimal number.

-.Pp
+.PP

 Unsuccessful commands are responded to with:
 Unsuccessful commands are responded to with:

-.Bd -filled -offset indent
-.Sm off
-.Xo Sy E Ar error-number
-.No \en Ar error-message
-.No \en
-.Xc
-.Sm on
-.Ed
-.Pp
-where
-.Ar error-number
+.RS
+.B E\fIerror-number\fR\en\fIerror-message\fR\en
+.RE
+.PP
+where 
+.I error-number

 is one of the possible error numbers described in
 is one of the possible error numbers described in

-.Xr intro 2
+.BR intro (2)

 and
 and

-.Ar error-message
+.I error-message

 is the corresponding error string as printed from a call to
 is the corresponding error string as printed from a call to

-.Xr perror 3 .
-.Pp
-The protocol is comprised of the
-following commands, which are sent as indicated - no spaces are supplied
-between the command and its arguments, or between its arguments, and
-.Ql \en
-indicates that a newline should be supplied:
-.Bl -tag -width Ds
-.Sm off
-.It Xo Sy \&O Ar device
-.No \en Ar mode No \en
-.Xc
-.Sm on
+.BR perror (3).
+.PP
+The protocol is comprised of the following commands, which are sent as 
+indicated - no spaces are supplied between the command and its arguments, or
+between its arguments, and \en indicates that a newline should be supplied:
+.TP
+.B O\fIdevice\fR\en\fImode\fR\en

 Open the specified 
 Open the specified 

-.Ar device
+.I device

 using the indicated
 using the indicated

-.Ar mode .
-.Ar Device
+.IR mode .
+.I Device

 is a full pathname and
 is a full pathname and

-.Ar mode
+.I mode

 is an
 is an

-.Tn ASCII
+.B ASCII

 representation of a decimal number suitable for passing to
 representation of a decimal number suitable for passing to

-.Xr open 2 .
-If a device had already been opened, it is closed before a 
-new open is performed.
-.Sm off
-.It Xo Sy C Ar device No \en
-.Xc
-.Sm on
+.BR open (2).
+If a device had already been opened, it is closed before a new open is
+performed.
+.TP
+.B C\fIdevice\fR\en

 Close the currently open device.  The
 Close the currently open device.  The

-.Ar device
+.I device

 specified is ignored.
 specified is ignored.

-.Sm off
-.It Xo Sy L
-.Ar whence No \en
-.Ar offset No \en
-.Xc
-.Sm on
+.TP
+.B L\fIwhence\fR\en\fIoffset\fR\en

 Perform an
 Perform an

-.Xr lseek 2
-operation using the specified parameters.
-The response value is that returned from the
-.Xr lseek
+.BR lseek (2)
+operation using the specified parameters. The response value is that returned
+from the
+.B lseek

 call.
 call.

-.Sm off
-.It Sy W Ar count No \en
-.Sm on
+.TP
+.B W\fIcount\fR\en

 Write data onto the open device.
 Write data onto the open device.

-.Nm rmt
+.B Rmt

 reads
 reads

-.Ar count
+.I count

 bytes from the connection, aborting if a premature end-of-file is encountered.
 The response value is that returned from the
 bytes from the connection, aborting if a premature end-of-file is encountered.
 The response value is that returned from the

-.Xr write 2
+.BR write (2)

 call.
 call.

-.Sm off
-.It Sy R Ar count No \en
-.Sm on
+.TP
+.B R\fIcount\fR\en

 Read
 Read

-.Ar count
-bytes of data from the open device.
-If
-.Ar count
-exceeds the size of the data buffer (10 kilobytes), it is
-truncated to the data buffer size.
-.Nm rmt
+.I count
+bytes of data from the open device. If
+.I count
+exceeds the size of the data buffer (10 kilobytes), it is truncated to the 
+data buffer size.
+.B Rmt

 then performs the requested 
 then performs the requested 

-.Xr read 2
+.BR read (2)

 and responds with 
 and responds with 

-.Sm off
-.Sy A Ar count-read No \en
-.Sm on
-if the read was successful; otherwise an error in the standard format 
-is returned.  If the read was successful, the data read is then sent.
-.Sm off
-.It Xo Sy I Ar operation
-.No \en Ar count No \en
-.Xc
-.Sm on
+.B A\fIcount-read\fR\en
+if the read was successful; otherwise an error in the standard format is 
+returned. If the read was successful, the data read is then sent.
+.TP
+.B I\fIoperation\fR\en\fIcount\fR\en

 Perform a
 Perform a

-.Dv MTIOCOP
-.Xr ioctl 2
+.B MTIOCOP
+.BR ioctl (2)

 command using the specified parameters.  The parameters are interpreted as the
 command using the specified parameters.  The parameters are interpreted as the

-.Tn ASCII
+.B ASCII

 representations of the decimal values to place in the 
 representations of the decimal values to place in the 

-.Ar mt_op
+.B mt_op

 and
 and

-.Ar mt_count
+.B mt_count

 fields of the structure used in the
 fields of the structure used in the

-.Xr ioctl
+.B ioctl

 call.  The return value is the
 call.  The return value is the

-.Ar count
+.I count

 parameter when the operation is successful.
 parameter when the operation is successful.

-.Pp
+.IP

 By issuing the
 By issuing the

-.Ql I-1\en0\en
+.B I-1\en0\en

 command, a client will specify that he is using the VERSION 1 protocol.
 command, a client will specify that he is using the VERSION 1 protocol.

-.Pp
+.IP

 For a VERSION 0 client, the
 For a VERSION 0 client, the

-.Ar operation
+.I operation

 parameter is the platform 
 parameter is the platform 

-.Ar mt_op
+.B mt_op

 value (could be different if the client and the
 value (could be different if the client and the

-.Nm
-server are on two different platforms). For a VERSION 1 client,
-the 
-.Ar operation
+.B rmt
+server are on two different platforms). For a VERSION 1 client, the 
+.I operation

 parameter is standardized as below:
 parameter is standardized as below:

-.Bl -tag -width Fl
-.It Ic 0
-Issue a MTWEOF command (write
-.Ar count
+.RS
+.TP
+.B 0
+Issue a 
+.B MTWEOF
+command (write
+.I count

 end-of-file records).
 end-of-file records).

-.It Ic 1
-Issue a MTFSF command (forward space over
-.Ar count
+.TP
+.B 1
+Issue a 
+.B MTFSF
+command (forward space over
+.I count

 file marks).
 file marks).

-.It Ic 2
-Issue a MTBSF command (backward space over
-.Ar count
+.TP
+.B 2
+Issue a 
+.B MTBSF
+command (backward space over
+.I count

 file marks).
 file marks).

-.It Ic 3
-Issue a MTFSR command (forward space
-.Ar count
+.TP
+.B 3
+Issue a 
+.B MTFSR 
+command (forward space
+.I count

 inter-record gaps).
 inter-record gaps).

-.It Ic 4
-Issue a MTBSR command (backward space
-.Ar count
+.TP
+.B 4
+Issue a 
+.B MTBSR
+command (backward space
+.I count

 inter-record gaps).
 inter-record gaps).

-.It Ic 5
-Issue a MTREW command (rewind).
-.It Ic 6
-Issue a MTOFFL command (rewind and put the drive offline).
-.It Ic 7
-Issue a MTNOP command (no operation, set status only).
-.El
-.Sm off
-.It Xo Sy i Ar operation
-.No \en Ar count No \en
-.Xc
-.Sm on
+.TP
+.B 5
+Issue a 
+.B MTREW
+command (rewind).
+.TP
+.B 6
+Issue a 
+.B MTOFFL
+command (rewind and put the drive offline).
+.TP
+.B 7
+Issue a
+.B MTNOP
+command (no operation, set status only).
+.RE
+.TP
+.B i\fIoperation\fR\en\fIcount\fR\en

 Perform an extended
 Perform an extended

-.Dv MTIOCOP
-.Xr ioctl 2
-command using the specified parameters.
-The parameters are interpreted as the
-.Tn ASCII
+.B MTIOCOP
+.BR ioctl (2)
+command using the specified parameters. The parameters are interpreted as the
+.B ASCII

 representations of the decimal values to place in the 
 representations of the decimal values to place in the 

-.Ar mt_op
+.B mt_op

 and
 and

-.Ar mt_count
+.B mt_count

 fields of the structure used in the
 fields of the structure used in the

-.Xr ioctl
+.B ioctl

 call.  The return value is the
 call.  The return value is the

-.Ar count
-parameter when the operation is successful.
-The possible operations are:
-.Bl -tag -width Fl
-.It Ic 0
-Issue a MTCACHE command (switch cache on).
-.It Ic 1
-Issue a MTNOCACHE command (switch cache off).
-.It Ic 2
-Issue a MTRETEN command (retension the tape).
-.It Ic 3
-Issue a MTERASE command (erase the entire tape).
-.It Ic 4
-Issue a MTEOM command (position to end of media).
-.It Ic 5
-Issue a MTNBSF command (backward space count files to BOF).
-.El
-.ne 1i
-.Sm off
-.It Sy S
-.Sm on
-Return the status of the open device, as
-obtained with a
-.Dv MTIOCGET
-.Xr ioctl
-call.  If the operation was successful,
-an ``ack'' is sent with the size of the
-status buffer, then the status buffer is
-sent (in binary, which is non-portable between different platforms).
-.Sm off
-.It Xo Sy s Ar sub-command
-.Xc
-.Sm on
-This is a replacement for the previous S command, portable across different
-platforms. If the open device is a magnetic tape, return members of the 
-magnetic tape status structure, as obtained with a
-.Dv MTIOCGET 
-ioctl call. If the open device is not a magnetic tape, an error is returned.
-If the 
-.Dv MTIOCGET
+.I count
+parameter when the operation is successful. The possible operations are:
+.RS
+.TP
+.B 0
+Issue a 
+.B MTCACHE
+command (switch cache on).
+.TP
+.B 1
+Issue a 
+.B MTNOCACHE
+command (switch cache off).
+.TP
+.B 2
+Issue a 
+.B MTRETEN
+command (retension the tape).
+.TP
+.B 3
+Issue a 
+.B MTERASE
+command (erase the entire tape).
+.TP
+.B 4
+Issue a 
+.B MTEOM
+command (position to end of media).
+.TP
+.B 5
+Issue a 
+.B MTNBSF
+command (backward space count files to BOF).
+.RE
+.TP
+.B S
+Return the status of the open device, as obtained with a
+.B MTIOCGET
+.B ioctl
+call.  If the operation was successful, an \*(lqack\*(rq is sent with the size
+of the status buffer, then the status buffer is sent (in binary, which is
+non-portable between different platforms).
+.TP
+.BI s sub-command
+This is a replacement for the previous 
+.B S 
+command, portable across different platforms. If the open device is a magnetic
+tape, return members of the magnetic tape status structure, as obtained with a
+.B MTIOCGET 
+ioctl call. If the open device is not a magnetic tape, an error is returned. If
+the 
+.B MTIOCGET

 operation was successful, the numerical value of the structure member is 
 returned in decimal. The following sub commands are supported:
 operation was successful, the numerical value of the structure member is 
 returned in decimal. The following sub commands are supported:

-.Bl -tag -width Fl
-.It Ic T
+.RS
+.TP
+.B T

 return the content of the structure member
 return the content of the structure member

-.Ar mt_type
+.B mt_type

 which contains the type of the magnetic tape device.
 which contains the type of the magnetic tape device.

-.It Ic D
+.TP
+.B D

 return the content of the structure member
 return the content of the structure member

-.Ar mt_dsreg
+.B mt_dsreg

 which contains the "drive status register".
 which contains the "drive status register".

-.It Ic E
+.TP
+.B E

 return the content of the structure member
 return the content of the structure member

-.Ar mt_erreg
+.B mt_erreg

 which contains the "error register". This structure member must be retrieved
 first because it is cleared after each
 which contains the "error register". This structure member must be retrieved
 first because it is cleared after each

-.Dv MTIOCGET
+.B MTIOCGET

 ioctl call.
 ioctl call.

-.It Ic R
+.TP
+.B R

 return the content of the structure member
 return the content of the structure member

-.Ar mt_resid
+.B mt_resid

 which contains the residual count of the last I/O.
 which contains the residual count of the last I/O.

-.It Ic F
+.TP
+.B F

 return the content of the structure member
 return the content of the structure member

-.Ar mt_fileno
+.B mt_fileno

 which contains the file number of the current tape position.
 which contains the file number of the current tape position.

-.It Ic B
+.TP
+.B B

 return the content of the structure member
 return the content of the structure member

-.Ar mt_blkno
+.B mt_blkno

 which contains the block number of the current tape position.
 which contains the block number of the current tape position.

-.It Ic f
+.TP
+.B f

 return the content of the structure member
 return the content of the structure member

-.Ar mt_flags
+.B mt_flags

 which contains MTF_ flags from the driver.
 which contains MTF_ flags from the driver.

-.It Ic b
+.TP
+.B b

 return the content of the structure member
 return the content of the structure member

-.Ar mt_bf
+.B mt_bf

 which contains the optimum blocking factor.
 which contains the optimum blocking factor.

-.El
-.El
-.Sm on
-.Pp
+.RE
+.PP

 Any other command causes 
 Any other command causes 

-.Nm
+.B rmt

 to exit.
 to exit.

-.Sh DIAGNOSTICS
+.SH DIAGNOSTICS

 All responses are of the form described above.
 All responses are of the form described above.

-.Sh SEE ALSO
-.Xr rcmd 3 ,
-.Xr rexec 3 ,
-.Xr /usr/include/sys/mtio.h ,
-.Xr rdump 8 ,
-.Xr rrestore 8
-.Sh BUGS
-People should be discouraged from using this for a remote
-file access protocol.
-.Sh AUTHOR
+.SH SEE ALSO
+.BR rcmd (3),
+.BR rexec (3),
+.I /usr/include/sys/mtio.h,
+.BR rdump (8),
+.BR rrestore (8)
+.SH BUGS
+People should be discouraged from using this for a remote file access protocol.
+.SH AUTHOR

 The
 The

-.Nm dump/restore
-backup suit 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 suit 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
 The

-.Nm dump/restore
-backup suit is available from 
-.br
-http://dump.sourceforge.net
-.Sh HISTORY
+.B dump/restore
+backup suit is available from <http://dump.sourceforge.net>
+.SH HISTORY

 The
 The

-.Nm
-command appeared in
-.Bx 4.2 .
+.B rmt
+command appeared in 4.2BSD.