From 153f9a83677b05d887ecec5dde9b4c4be8e3c8ca Mon Sep 17 00:00:00 2001 From: Stelian Pop Date: Wed, 24 Jul 2002 14:11:59 +0000 Subject: [PATCH] Man pages rewrite. --- CHANGES | 6 +- dump/dump.8.in | 984 +++++++++++++++++----------------- restore/restore.8.in | 1208 +++++++++++++++++++++--------------------- rmt/rmt.8.in | 504 +++++++++--------- 4 files changed, 1334 insertions(+), 1368 deletions(-) diff --git a/CHANGES b/CHANGES index efa53e8..5747d64 100644 --- 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 ????????????????) ====================================================================== @@ -37,6 +37,10 @@ Changes between versions 0.4b29 and 0.4b30 (released ????????????????) Eric S. Raymond 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) ================================================================== diff --git a/dump/dump.8.in b/dump/dump.8.in index c809558..c92f90c 100644 --- 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. .\" -.\" $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 001, 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 001, 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 . 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 -. -.Sh AVAILABILITY +.B dump/restore +backup suite was ported to Linux's Second Extended File System by Remy Card +. 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 . +.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 +.SH HISTORY A -.Nm +.B dump command appeared in -.At v6 . +.B Version 6 AT&T UNIX. diff --git a/restore/restore.8.in b/restore/restore.8.in index 4dbaece..92544bf 100644 --- 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. .\" -.\" $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 001, 002 etc. -.It Fl N +.B restore +tries to read in sequence from +.I 001, 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 : 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 , got -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 -.It Tape read error while skipping over inode -.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 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 : 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 , got +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 +.TP +.I Tape read error while skipping over inode +.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 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 . 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 -. -.Sh AVAILABILITY +.B dump/restore +backup suite was ported to Linux's Second Extended File System by Remy Card +. 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 . +.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 +.SH HISTORY 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 6e93213..228d2b2 100644 --- 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. .\" -.\" $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 . 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 -. -.Sh AVAILABILITY +.B dump/restore +backup suit was ported to Linux's Second Extended File System by Remy Card +. 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 . +.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 +.SH HISTORY The -.Nm -command appeared in -.Bx 4.2 . +.B rmt +command appeared in 4.2BSD. -- 2.39.2