diff options
Diffstat (limited to 'usr.sbin/fdread/fdread.1')
| -rw-r--r-- | usr.sbin/fdread/fdread.1 | 233 |
1 files changed, 233 insertions, 0 deletions
diff --git a/usr.sbin/fdread/fdread.1 b/usr.sbin/fdread/fdread.1 new file mode 100644 index 0000000..d29a4a4 --- /dev/null +++ b/usr.sbin/fdread/fdread.1 @@ -0,0 +1,233 @@ +.\" +.\" Copyright (c) 2001 Joerg Wunsch +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.\" +.Dd May 14, 2001 +.Dt FDREAD 1 +.Os +.Sh NAME +.Nm fdread +.Nd read floppy disks +.Sh SYNOPSIS +.Nm +.Op Fl qr +.Op Fl d Ar device +.Op Fl f Ar fillbyte +.Op Fl o Ar file +.Nm +.Op Fl d Ar device +.Fl I Ar numsects +.Op Fl t Ar trackno +.Sh DESCRIPTION +The +.Nm +utility reads floppy disks. +Effective read blocking based on the track +size is performed, and floppy-specific error recovery of otherwise +bad blocks can be enabled. +.Pp +The +.Nm +utility +will always read an entire floppy medium, and write its contents to +the respective output file. +Unlike other tools like +.Xr dd 1 , +.Nm +automatically uses a read block size that is more efficient than +reading single blocks (usually one track of data at a time), but +falls back to reading single floppy sectors in case of an input/output +error occurred, in order to obtain as much valid data as possible. +While +.Nm +is working, kernel error reporting for floppy errors is turned off, so +the console and/or syslog are not flooded with kernel error messages. +.Pp +The +.Nm +utility accepts the following options: +.Bl -tag -width indent +.It Fl q +Turn on quiet mode. +By default, the medium parameters of the device +are being written to standard error output, progress will be indicated +by the approximate number of kilobytes read so far, and errors will be +printed out in detail, including the information about the location of +recovered data in the output. +In quiet mode, none of these messages +will be generated. +.It Fl r +Enable error recovery. +By default, +.Nm +stops after the first unrecovered read error, much like +.Xr dd 1 +does. +In recovery mode, however, one of two recovery actions will be +taken: +.Bl -bullet +.It +If the error was a CRC error in the data field, the +kernel is told to ignore the error, and data are transferred to the +output file anyway. +.Bf -emphasis +Note that this will cause the erroneous data +to be included in the output file! +.Ef +Still, this is the best recovery action that can be taken at all. +.It +All other errors are really fatal (usually, the FDC did not find the +sector ID fields), thus a dummy block with fill +bytes will be included in the output file. +.El +.Pp +Unless operating in quiet mode, the action taken and the location of +the error in the output file will be displayed. +.It Fl d Ar device +Specify the input floppy device, defaulting to +.Pa /dev/fd0 . +The parameter +.Ar device +must be a valid floppy disk device. +.It Fl f Ar fillbyte +Value of the fill byte used for dummy blocks in the output file in +recovery mode. +Defaults to +.Ql 0xf0 . +(Mnemonic: +.Dq foo . ) +The value can be specified using the usual C language notation of +the number base. +.It Fl o Ar file +Specify the output file to be +.Ar file . +By default, the data will be written to standard output. +.It Fl I Ar numsects +Read +.Ar numsects +sector ID fields, and write out their contents to standard output. +Each sector ID field contains recorded values for the cylinder number +.Pq Ql C , +the head number +.Pq Ql H , +the record number (sector number starting with 1) +.Pq Ql R , +and the +.Em sector shift value +(0 = 128 bytes, 1 = 256 bytes, 2 = 512 bytes, 3 = 1024 bytes) +.Pq Ql N . +The +.Fl I +option is mutually exclusive with all other options except +.Fl d Ar device +and +.Fl t Ar trackno . +.It Fl t Ar trackno +Specify the track number (cylinder number * number of heads + head +number) to read the sector ID fields from; only allowed together with +the +.Fl I Ar numsects +option. +.El +.Sh FILES +.Bl -tag -width /dev/fd0 +.It Pa /dev/fd0 +Default device to read from. +.El +.Sh EXIT STATUS +The +.Nm +utility sets the exit value according to +.Xr sysexits 3 . +In recovery mode, the exit value will be set to +.Dv EX_IOERR +if any error occurred during processing (even in quiet mode). +.Sh DIAGNOSTICS +Unless running in quiet mode, upon encountering an error, the status +of the floppy disc controller (FDC) will be printed out, both in +hexadecimal form, followed by a textual description that translates +those values into a human-readable form for the most common error +cases that can happen in a PC environment. +.Pp +The FDC error status includes the three FDC status registers +.Ql ST0 , +.Ql ST1 , +and +.Ql ST2 , +as well as the location of the error (physical cylinder, head, and sector +number, plus the +.Dq sector shift value , +respectively). +See the manual for the NE765 or compatible for details +about the status register contents. +.Pp +The FDC's status is then examined to determine whether the error is +deemed to be recoverable. +If error recovery was requested, the +location of the bad block in the output file is indicated by its +(hexadecimal) bounds. +Also, a summary line indicating the total number +of transfer errors will be printed before exiting. +.Sh SEE ALSO +.Xr dd 1 , +.Xr fdwrite 1 , +.Xr sysexits 3 , +.Xr fdc 4 , +.Xr fdcontrol 8 +.Sh HISTORY +The +.Nm +utility was written mainly to provide a means of recovering at least some of +the data on bad media, and to obviate the need to invoke +.Xr dd 1 +with too many hard to memorize options that might be useful to handle +a floppy. +.Pp +The command appeared in +.Fx 5.0 . +.Sh AUTHORS +Program and man page by +.An J\(:org Wunsch . +.Sh BUGS +Concurrent traffic on the second floppy drive located at the same FDC +will make error recovery attempts pointless, since the FDC status +obtained after a read error occurred cannot be guaranteed to actually +belong to the erroneous transfer. +Thus using option +.Fl r +is only reliable if +.Ar device +is the only active drive on that controller. +.Pp +No attempt beyond the floppy error retry mechanism of +.Xr fdc 4 +is made in order to see whether bad sectors could still be read +without errors by trying multiple times. +.Pp +Bits that are (no longer) available on the floppy medium cannot be +guessed by +.Nm . |
