Subject: kern/32830: sd(4) contains incorrect & incomplete information
To: None <email@example.com, firstname.lastname@example.org,>
From: None <kre@munnari.OZ.AU>
Date: 02/14/2006 06:40:00
>Synopsis: sd(4) contains incorrect & incomplete information
>Arrival-Date: Tue Feb 14 06:40:00 +0000 2006
>Originator: Robert Elz
>Release: NetBSD 3.99.15 (--current as of a few hours ago)
Prince of Songkla University
System: NetBSD jade.coe.psu.ac.th 3.99.15 NetBSD 3.99.15 (GENERIC-1.696-20060125) #8: Wed Jan 25 04:59:39 ICT 2006 email@example.com:/usr/obj/current/kernels/JADE_ASUS i386
sd(4) says ...
The following ioctl(2) calls apply to SCSI disks as well as to other
disks. They are defined in the header file <disklabel.h>.
There is no <disklabel.h>, the include file is <sys/disklabel.h>
but that's trivial, and almost anyone can work that out I suspect.
More importantly, the ioctl(2) calls that follow aren't defined in
disklabel.h itself, nor does including disklabel.h manage to
include some other header file which does define them.
What disklabel.h does define are the data structures needed for
(most of) the ioctl() commands to be used, without defining the
ioctls themselves. The ioctl definitions are in <sys/dkio.h>.
And while I am here: Why are these ioctls only defined (according
to the manual) for SCSI drives? They all work just the same
for IDE drives, and I'd expect others as well. cd(4) does document
DIOCSDINFO, but none of the others (though it probably supports
more of the set listed in sd(4) than just that one - at least it
gets the header files closer to correct - it doesn't mention dkio.h
either though, which would be needed to use DIOCSDINFO). Shouldn't
there be some place that all the disk related ioctl calls that are
common to just about everything (including ccd, cgd, raid, ...) can
be documented once, and then just SEE ALSO'd from other places?
[Maybe dk(4) or dkioctl(4) or ... ??]
[I am trying to work out where I should document a new
ioctl call, at the minute, the likely answer looks to be
"don't bother, most of the rest are not documented".]
RTFM (and the header files).
Make it say something like:
They are defined in the pair of header files <sys/disklabel.h> and
An alternative would be to have <sys/disklabel.h> include
<sys/dkio.h> (at least, #if !defined(KERNEL)), but that's not
the normal NetBSD way.