Second round of floppy disk driver documentation updates: document the

changes in the userland utilities.  For fdcontrol(8), i now finally
keep my promise made more than 7 years ago that ``the fdcontrol
utility is currently under development and the user interface will
likely change''. :-)

1 files changed, 61 insertions, 65 deletions

diff --git a/usr.sbin/fdformat/fdformat.1 b/usr.sbin/fdformat/fdformat.1
index d568181..ef542a7 100644
--- a/usr.sbin/fdformat/fdformat.1
+++ b/usr.sbin/fdformat/fdformat.1
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 2, 2001
+.Dd December 25, 2001
 .Os
 .Dt FDFORMAT 1
 .Sh NAME
@@ -32,84 +32,74 @@
 .Nd format floppy disks
 .Sh SYNOPSIS
 .Nm
-.Op Fl q
-.Op Fl y
-.Op Fl v | Fl n
-.Op Fl f Ar capacity
-.Op Fl c Ar cyls
-.Op Fl s Ar secs
-.Op Fl h Ar heads
-.Nm
-.Op Fl r Ar rate
-.Op Fl g Ar gap3len
-.Op Fl i Ar intleave
-.Op Fl S Ar secshft
-.Op Fl F Ar fillbyte
-.Op Fl t Ar steps_per_track
-.Ar device_name
+.Op Fl F Ar fill
+.Op Fl f Ar fmt
+.Op Fl s Ar fmtstr
+.Op Fl nqvy
+.Ar device
 .Sh DESCRIPTION
-.Nm Fdformat
-formats a floppy disk at device
-.Ar device_name .
-.Ar Device_name
-may be given either with a full path
+The
+.Nm
+utility formats a floppy disk at
+.Ar device ,
+where
+.Ar device
+may either be given as a full path
 name of a device node for a floppy disk drive
 (e.g.\&
 .Pa /dev/fd0 ) ,
-or a default name in an abbreviated form
+or using an abbreviated name that will be looked up
+under
+.Pa /dev
 (e.g.\&
 .Em fd0 ) .
-In the latter case, the name is constructed by prepending
-.Pa /dev/
-and appending a
-.Em .capacity
-to the
-.Ar device_name .
-Note that any geometry constraints of the device node
-(minor device number)
-are meaningless, since they're overridden by
-.Nm .
 .Pp
 The options are as follows:
 .Bl -tag -width 10n -offset indent
+.It Fl F Ar fill
+Use
+.Ar fill
+as the fill byte for newly formatted sectors.
+.Ar fill
+must be a number in the range 0 through 255 using common C
+language notation.  The default value is
+.Em 0xf5 .
+.It Fl f Ar fmt
+Specify the density settings for a
+.Ar fmt
+kilobyte format, as described in
+.Xr fdcontrol 8 .
+.It Fl s Ar fmtstr
+Specify the density settings using explicit parameters, as
+described in
+.Xr fdcontrol 8 .
+.It Fl n
+Don't verify floppy after formatting.
 .It Fl q
 Suppress any normal output from the command, and don't ask the
 user for a confirmation whether to format the floppy disk at
-.Ar device_name .
-.It Fl y
-Suppress confirmation request by automagically responding "yes", but still
-report format status.
-.It Fl f Ar capacity
-The normal way to specify the desired formatting parameters.
-.Ar Capacity
-is the number of kilobytes to format.
-Valid choices are 360, 720, 800, 820,
-1200, 1440, 1480 or 1720.
-.It Fl n
-Don't verify floppy after formatting.
+.Ar device .
 .It Fl v
 Don't format, verify only.
-.It Fl c Ar cyls
-Number of cylinders: 40 or 80.
-.It Fl s Ar secs
-Number of sectors per track: 9, 10, 15 or 18.
-.It Fl h Ar heads
-Number of floppy heads: 1 or 2.
-.It Fl r Ar rate
-Data rate: 250, 300 or 500 kbps.
-.It Fl g Ar gap3len
-Gap length.
-.It Fl i Ar intleave
-Interleave factor.
-.It Fl S Ar secshft
-Sector size: 0=128, 1=256, 2=512 bytes.
-.It Fl F Ar fillbyte
-Fill byte.
-.It Fl t Ar steps_per_track
-Number of steps per track.
-An alternate method to specify the geometry data to write to the floppy disk.
+.It Fl y
+Do not ask for confirmation whether to format the floppy disk but
+still report formatting status.
 .El
 .Pp
+For non-autoselecting subdevices, neither
+.Fl f Ar fmt
+nor
+.Fl s Ar fmtstr
+may be specified, since the preconfigured media density settings
+from the kernel driver will always be used.  However, if
+.Ar device
+is a device with automatic media density selection (see
+.Xr fdc 4 ) ,
+both methods can be used to override the density settings for the
+newly formatted medium (without permanently changing the density
+settings of
+.Ar device ) .
+.Pp
 If the
 .Fl q
 flag has not been specified, the user is asked for a confirmation
@@ -121,7 +111,7 @@ must be given.
 .Pp
 Note that
 .Nm
-does only perform low-level formatting.  In case you wish to create
+does only perform low-level formatting.  In order to create
 a file system on the medium, see the commands
 .Xr newfs 8
 for an
@@ -144,7 +134,8 @@ while it's being verified, and if an error has been detected, it
 will finally change to
 .Sq Em E .
 Detailed status information (cylinder, head and sector number, and the
-exact cause of the error) will then be printed for up to 10 errors.
+exact cause of the error) will be printed for up to 10 errors after the
+entire formatting process has completed.
 .Pp
 An exit status of 0 is returned upon successful operation.
 Exit status
@@ -153,6 +144,7 @@ of 2 reflects invalid arguments given to the program (along with an
 appropriate information written to diagnostic output).
 .Sh SEE ALSO
 .Xr fdc 4 ,
+.Xr fdcontrol 8 ,
 .Xr newfs 8 ,
 .Xr newfs_msdos 8
 .Sh HISTORY
@@ -165,6 +157,10 @@ floppy disk driver.
 It later became part of the
 .Fx 1.1
 system.
+Starting with
+.Fx 5.0 ,
+it uses the unified density specifications as described in
+.Xr fdcontrol 8 .
 .Sh AUTHORS
 .An -nosplit
 The program has been contributed by