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