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.\" 27.Dd May 14, 2001 28.Dt FDREAD 1 29.Os 30.Sh NAME 31.Nm fdread 32.Nd read floppy disks 33.Sh SYNOPSIS 34.Nm 35.Op Fl qr 36.Op Fl d Ar device 37.Op Fl f Ar fillbyte 38.Op Fl o Ar file 39.Nm 40.Op Fl d Ar device 41.Fl I Ar numsects 42.Op Fl t Ar trackno 43.Sh DESCRIPTION 44The 45.Nm 46utility reads floppy disks. 47Effective read blocking based on the track 48size is performed, and floppy-specific error recovery of otherwise 49bad blocks can be enabled. 50.Pp 51The 52.Nm 53utility 54will always read an entire floppy medium, and write its contents to 55the respective output file. 56Unlike 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. 74By default, the medium parameters of the device 75are being written to standard error output, progress will be indicated 76by the approximate number of kilobytes read so far, and errors will be 77printed out in detail, including the information about the location of 78recovered data in the output. 79In quiet mode, none of these messages 80will be generated. 81.It Fl r 82Enable error recovery. 83By default, 84.Nm 85stops after the first unrecovered read error, much like 86.Xr dd 1 87does. 88In recovery mode, however, one of two recovery actions will be 89taken: 90.Bl -bullet 91.It 92If the error was a CRC error in the data field, the 93kernel is told to ignore the error, and data are transferred to the 94output file anyway. 95.Bf -emphasis 96Note that this will cause the erroneous data 97to be included in the output file! 98.Ef 99Still, this is the best recovery action that can be taken at all. 100.It 101All other errors are really fatal (usually, the FDC did not find the 102sector ID fields), thus a dummy block with fill 103bytes will be included in the output file. 104.El 105.Pp 106Unless operating in quiet mode, the action taken and the location of 107the error in the output file will be displayed. 108.It Fl d Ar device 109Specify the input floppy device, defaulting to 110.Pa /dev/fd0 . 111The parameter 112.Ar device 113must be a valid floppy disk device. 114.It Fl f Ar fillbyte 115Value of the fill byte used for dummy blocks in the output file in 116recovery mode. 117Defaults to 118.Ql 0xf0 . 119(Mnemonic: 120.Dq foo . ) 121The value can be specified using the usual C language notation of 122the number base. 123.It Fl o Ar file 124Specify the output file to be 125.Ar file . 126By default, the data will be written to standard output. 127.It Fl I Ar numsects 128Read 129.Ar numsects 130sector ID fields, and write out their contents to standard output. 131Each sector ID field contains recorded values for the cylinder number 132.Pq Ql C , 133the head number 134.Pq Ql H , 135the record number (sector number starting with 1) 136.Pq Ql R , 137and the 138.Em sector shift value 139(0 = 128 bytes, 1 = 256 bytes, 2 = 512 bytes, 3 = 1024 bytes) 140.Pq Ql N . 141The 142.Fl I 143option is mutually exclusive with all other options except 144.Fl d Ar device 145and 146.Fl t Ar trackno . 147.It Fl t Ar trackno 148Specify the track number (cylinder number * number of heads + head 149number) to read the sector ID fields from; only allowed together with 150the 151.Fl I Ar numsects 152option. 153.El 154.Sh FILES 155.Bl -tag -width /dev/fd0 156.It Pa /dev/fd0 157Default device to read from. 158.El 159.Sh EXIT STATUS 160The 161.Nm 162utility sets the exit value according to 163.Xr sysexits 3 . 164In recovery mode, the exit value will be set to 165.Dv EX_IOERR 166if any error occurred during processing (even in quiet mode). 167.Sh DIAGNOSTICS 168Unless running in quiet mode, upon encountering an error, the status 169of the floppy disc controller (FDC) will be printed out, both in 170hexadecimal form, followed by a textual description that translates 171those values into a human-readable form for the most common error 172cases that can happen in a PC environment. 173.Pp 174The FDC error status includes the three FDC status registers 175.Ql ST0 , 176.Ql ST1 , 177and 178.Ql ST2 , 179as well as the location of the error (physical cylinder, head, and sector 180number, plus the 181.Dq sector shift value , 182respectively). 183See the manual for the NE765 or compatible for details 184about the status register contents. 185.Pp 186The FDC's status is then examined to determine whether the error is 187deemed to be recoverable. 188If error recovery was requested, the 189location of the bad block in the output file is indicated by its 190(hexadecimal) bounds. 191Also, a summary line indicating the total number 192of transfer errors will be printed before exiting. 193.Sh SEE ALSO 194.Xr dd 1 , 195.Xr fdwrite 1 , 196.Xr sysexits 3 , 197.Xr fdc 4 , 198.Xr fdcontrol 8 199.Sh HISTORY 200The 201.Nm 202utility was written mainly to provide a means of recovering at least some of 203the data on bad media, and to obviate the need to invoke 204.Xr dd 1 205with too many hard to memorize options that might be useful to handle 206a floppy. 207.Pp 208The command appeared in 209.Fx 5.0 . 210.Sh AUTHORS 211Program and man page by 212.An J\(:org Wunsch . 213.Sh BUGS 214Concurrent traffic on the second floppy drive located at the same FDC 215will make error recovery attempts pointless, since the FDC status 216obtained after a read error occurred cannot be guaranteed to actually 217belong to the erroneous transfer. 218Thus using option 219.Fl r 220is only reliable if 221.Ar device 222is the only active drive on that controller. 223.Pp 224No attempt beyond the floppy error retry mechanism of 225.Xr fdc 4 226is made in order to see whether bad sectors could still be read 227without errors by trying multiple times. 228.Pp 229Bits that are (no longer) available on the floppy medium cannot be 230guessed by 231.Nm . 232