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