1 files changed, 184 insertions, 0 deletions
diff --git a/usr.sbin/fdread/fdread.1 b/usr.sbin/fdread/fdread.1
new file mode 100644
index 0000000..7e21404
--- /dev/null
+++ b/usr.sbin/fdread/fdread.1
@@ -0,0 +1,184 @@
+.\"
+.\" 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
+.Os FreeBSD
+.Dt FDREAD 1
+.Sh NAME
+.Nm fdread
+.Nd read floppy disks
+.Sh SYNOPSIS
+.Nm
+.Op Fl q
+.Op Fl r
+.Op Fl d Ar device
+.Op Fl f Ar fillbyte
+.Op Fl o Ar file
+.Sh DESCRIPTION
+.Nm Fdread
+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
+.Nm Fdread
+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.
+.Sh Options
+The options are as follows:
+.Bl -tag -width XXXX -offset 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 -offset indent
+.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.
+.Em Note that this will cause the erroneous data
+.Em to be included in the output file !
+Still, this is the best recovery action that can be taken at all.
+.It
+All other errors are really fatal (usually, the FDC didn't 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.
+.El
+.Sh FILES
+.Bl -tag -width XXXXXXXX -offset indent
+.It Pa /dev/fd0
+Default device to read from.
+.Sh DIAGNOSTICS
+.Nm Fdread
+sets the exit value according to
+.Xr sysexits 3 .
+In recovery mode, the exit value will be set to
+.Sy EX_IOERR
+if any error occurred during processing (even in quiet mode).
+.Pp
+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 fdc 4 ,
+.Xr fdcontrol 8 ,
+.Xr fdwrite 1 ,
+.Xr sysexits 3
+.Sh HISTORY
+.Nm Fdread
+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
+.ie t J\(:org Wunsch.
+.el Joerg 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 fdread .