>Number:         32830
>Category:       kern
>Synopsis:       sd(4) contains incorrect & incomplete information
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    kern-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>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)
>Organization:
	Prince of Songkla University
>Environment:
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 kre@jade.coe.psu.ac.th:/usr/obj/current/kernels/JADE_ASUS i386
Architecture: i386
Machine: i386
>Description:

	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".]

>How-To-Repeat:
	RTFM (and the header files).

>Fix:
	Make it say something like:

	They are defined in the pair of header files <sys/disklabel.h> and
	<sys/dkio.h>.

	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.