NetBSD Problem Report #32830

From kre@munnari.OZ.AU  Tue Feb 14 06:38:47 2006
Return-Path: <kre@munnari.OZ.AU>
Received: from jade.coe.psu.ac.th (unknown [202.12.74.196])
	by narn.netbsd.org (Postfix) with ESMTP id 5855763B879
	for <gnats-bugs@gnats.NetBSD.org>; Tue, 14 Feb 2006 06:38:46 +0000 (UTC)
Message-Id: <200602140638.k1E6cYoV001164@jade.coe.psu.ac.th>
Date: Tue, 14 Feb 2006 13:38:34 +0700 (ICT)
From: kre@munnari.OZ.AU
To: gnats-bugs@netbsd.org
Subject: sd(4) contains incorrect & incomplete information
X-Send-Pr-Version: 3.95

>Number:         32830
>Category:       kern
>Synopsis:       sd(4) contains incorrect & incomplete information
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    kern-bug-people
>State:          closed
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Tue Feb 14 06:40:00 +0000 2006
>Closed-Date:    Thu Jun 09 14:53:25 +0000 2016
>Last-Modified:  Thu Jun 09 14:55:01 +0000 2016
>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.

>Release-Note:

>Audit-Trail:

State-Changed-From-To: open->closed
State-Changed-By: kre@NetBSD.org
State-Changed-When: Thu, 09 Jun 2016 14:53:25 +0000
State-Changed-Why:
Finally fixed (10 years for a doc bug!)


From: "Robert Elz" <kre@netbsd.org>
To: gnats-bugs@gnats.NetBSD.org
Cc: 
Subject: PR/32830 CVS commit: src/share/man/man4
Date: Thu, 9 Jun 2016 14:52:48 +0000

 Module Name:	src
 Committed By:	kre
 Date:		Thu Jun  9 14:52:48 UTC 2016

 Modified Files:
 	src/share/man/man4: sd.4

 Log Message:
 PR kern/32830 (from 10 years ago, pre NetBSD 4...)
 Reference correct include files needed for the ioctl calls mentioned.


 To generate a diff of this commit:
 cvs rdiff -u -r1.18 -r1.19 src/share/man/man4/sd.4

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

>Unformatted:

Home	PR Database Search