usr.sbin/fdread/fdread.1

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