1.\" 2.\" Copyright (c) 2001 Joerg Wunsch 3.\" 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.\" 29.Dd May 14, 2001 30.Os 31.Dt FDREAD 1 32.Sh NAME 33.Nm fdread 34.Nd read floppy disks 35.Sh SYNOPSIS 36.Nm 37.Op Fl qr 38.Op Fl d Ar device 39.Op Fl f Ar fillbyte 40.Op Fl o Ar file 41.Nm 42.Op Fl d Ar device 43.Fl I Ar numsects 44.Op Fl t Ar trackno 45.Sh DESCRIPTION 46The 47.Nm 48utility reads floppy disks. Effective read blocking based on the track 49size is performed, and floppy-specific error recovery of otherwise 50bad blocks can be enabled. 51.Pp 52The 53.Nm 54utility 55will always read an entire floppy medium, and write its contents to 56the respective output file. Unlike other tools like 57.Xr dd 1 , 58.Nm 59automatically uses a read block size that is more efficient than 60reading single blocks (usually one track of data at a time), but 61falls back to reading single floppy sectors in case of an input/output 62error occurred, in order to obtain as much valid data as possible. 63While 64.Nm 65is working, kernel error reporting for floppy errors is turned off, so 66the console and/or syslog are not flooded with kernel error messages. 67.Pp 68The 69.Nm 70utility accepts the following options: 71.Bl -tag -width indent 72.It Fl q 73Turn on quiet mode. By default, the medium parameters of the device 74are being written to standard error output, progress will be indicated 75by the approximate number of kilobytes read so far, and errors will be 76printed out in detail, including the information about the location of 77recovered data in the output. In quiet mode, none of these messages 78will be generated. 79.It Fl r 80Enable error recovery. By default, 81.Nm 82stops after the first unrecovered read error, much like 83.Xr dd 1 84does. In recovery mode, however, one of two recovery actions will be 85taken: 86.Bl -bullet 87.It 88If the error was a CRC error in the data field, the 89kernel is told to ignore the error, and data are transferred to the 90output file anyway. 91.Bf -emphasis 92Note that this will cause the erroneous data 93to be included in the output file! 94.Ef 95Still, this is the best recovery action that can be taken at all. 96.It 97All other errors are really fatal (usually, the FDC didn't find the 98sector ID fields), thus a dummy block with fill 99bytes will be included in the output file. 100.El 101.Pp 102Unless operating in quiet mode, the action taken and the location of 103the error in the output file will be displayed. 104.It Fl d Ar device 105Specify the input floppy device, defaulting to 106.Pa /dev/fd0 . 107The parameter 108.Ar device 109must be a valid floppy disk device. 110.It Fl f Ar fillbyte 111Value of the fill byte used for dummy blocks in the output file in 112recovery mode. Defaults to 113.Ql 0xf0 . 114(Mnemonic: 115.Dq foo . ) 116The value can be specified using the usual C language notation of 117the number base. 118.It Fl o Ar file 119Specify the output file to be 120.Ar file . 121By default, the data will be written to standard output. 122.It Fl I Ar numsects 123Read 124.Ar numsects 125sector ID fields, and write out their contents to standard output. 126Each sector ID field contains recorded values for the cylinder number 127.Pq Ql C , 128the head number 129.Pq Ql H , 130the record number (sector number starting with 1) 131.Pq Ql R , 132and the 133.Em sector shift value 134(0 = 128 bytes, 1 = 256 bytes, 2 = 512 bytes, 3 = 1024 bytes) 135.Pq Ql N . 136The 137.Fl I 138option is mutually exclusive with all other options except 139.Fl d Ar device 140and 141.Fl t Ar trackno . 142.It Fl t Ar trackno 143Specify the track number (cylinder number * number of heads + head 144number) to read the sector ID fields from; only allowed together with 145the 146.Fl I Ar numsects 147option. 148.El 149.Sh FILES 150.Bl -tag -width /dev/fd0 151.It Pa /dev/fd0 152Default device to read from. 153.El 154.Sh DIAGNOSTICS 155The 156.Nm 157utility sets the exit value according to 158.Xr sysexits 3 . 159In recovery mode, the exit value will be set to 160.Dv EX_IOERR 161if any error occurred during processing (even in quiet mode). 162.Pp 163Unless running in quiet mode, upon encountering an error, the status 164of the floppy disc controller (FDC) will be printed out, both in 165hexadecimal form, followed by a textual description that translates 166those values into a human-readable form for the most common error 167cases that can happen in a PC environment. 168.Pp 169The FDC error status includes the three FDC status registers 170.Ql ST0 , 171.Ql ST1 , 172and 173.Ql ST2 , 174as well as the location of the error (physical cylinder, head, and sector 175number, plus the 176.Dq sector shift value , 177respectively). See the manual for the NE765 or compatible for details 178about the status register contents. 179.Pp 180The FDC's status is then examined to determine whether the error is 181deemed to be recoverable. If error recovery was requested, the 182location of the bad block in the output file is indicated by its 183(hexadecimal) bounds. Also, a summary line indicating the total number 184of transfer errors will be printed before exiting. 185.Sh SEE ALSO 186.Xr dd 1 , 187.Xr fdwrite 1 , 188.Xr sysexits 3 , 189.Xr fdc 4 , 190.Xr fdcontrol 8 191.Sh HISTORY 192The 193.Nm 194utility was written mainly to provide a means of recovering at least some of 195the data on bad media, and to obviate the need to invoke 196.Xr dd 1 197with too many hard to memorize options that might be useful to handle 198a floppy. 199.Pp 200The command appeared in 201.Fx 5.0 . 202.Sh AUTHORS 203Program and man page by 204.An J\(:org Wunsch . 205.Sh BUGS 206Concurrent traffic on the second floppy drive located at the same FDC 207will make error recovery attempts pointless, since the FDC status 208obtained after a read error occurred cannot be guaranteed to actually 209belong to the erroneous transfer. Thus using option 210.Fl r 211is only reliable if 212.Ar device 213is the only active drive on that controller. 214.Pp 215No attempt beyond the floppy error retry mechanism of 216.Xr fdc 4 217is made in order to see whether bad sectors could still be read 218without errors by trying multiple times. 219.Pp 220Bits that are (no longer) available on the floppy medium cannot be 221guessed by 222.Nm . 223