NetBSD Problem Report #32830
From kre@munnari.OZ.AU Tue Feb 14 06:38:47 2006
Received: from jade.coe.psu.ac.th (unknown [188.8.131.52])
by narn.netbsd.org (Postfix) with ESMTP id 5855763B879
for <gnats-bugs@gnats.NetBSD.org>; Tue, 14 Feb 2006 06:38:46 +0000 (UTC)
Date: Tue, 14 Feb 2006 13:38:34 +0700 (ICT)
Subject: sd(4) contains incorrect & incomplete information
>Synopsis: sd(4) contains incorrect & incomplete information
>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)
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 firstname.lastname@example.org:/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.
State-Changed-When: Thu, 09 Jun 2016 14:53:25 +0000
Finally fixed (10 years for a doc bug!)
From: "Robert Elz" <email@example.com>
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
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.
$NetBSD: query-full-pr,v 1.39 2013/11/01 18:47:49 spz Exp $
$NetBSD: gnats_config.sh,v 1.8 2006/05/07 09:23:38 tsutsui Exp $
Copyright © 1994-2014
The NetBSD Foundation, Inc. ALL RIGHTS RESERVED.