NetBSD Problem Report #37427
From martin@duskware.de Sat Nov 24 13:02:47 2007
Return-Path: <martin@duskware.de>
Received: from mail.netbsd.org (mail.netbsd.org [204.152.190.11])
by narn.NetBSD.org (Postfix) with ESMTP id 722AC63B88C
for <gnats-bugs@gnats.netbsd.org>; Sat, 24 Nov 2007 13:02:47 +0000 (UTC)
Message-Id: <20071124112422.B62C863B88C@narn.NetBSD.org>
Date: Sat, 24 Nov 2007 11:24:22 +0000 (UTC)
From: mmondor@pulsar-zone.net
Reply-To: mmondor@pulsar-zone.net
To: netbsd-bugs-owner@NetBSD.org
Subject: document _ksem_* syscalls
X-Send-Pr-Version: www-1.0
>Number: 37427
>Category: kern
>Synopsis: document _ksem_* syscalls
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: pgoyette
>State: closed
>Class: doc-bug
>Submitter-Id: net
>Arrival-Date: Sat Nov 24 13:05:00 +0000 2007
>Closed-Date: Fri Feb 05 05:30:44 +0000 2016
>Last-Modified: Fri Feb 05 05:30:44 +0000 2016
>Originator: Matthew Mondor
>Release: 4.99.35
>Organization:
>Environment:
NetBSD sat.xisop 4.99.35 NetBSD 4.99.35 (GENERIC_LAPTOP_MM) #3: Mon Nov 12 02:07:25 EST 2007 root@sat.xisop:/usr/src/sys/arch/i386/compile/GENERIC_LAPTOP_MM i386
>Description:
Reminder to write _ksem_* system calls manual pages in section 2. Those are internally used by the POSIX semaphores librt functions.
>How-To-Repeat:
>Fix:
>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: kern-bug-people->pgoyette
Responsible-Changed-By: pgoyette@NetBSD.org
Responsible-Changed-When: Sat, 28 Nov 2015 04:01:12 +0000
Responsible-Changed-Why:
Might as well take responsibility
State-Changed-From-To: open->feedback
State-Changed-By: pgoyette@NetBSD.org
State-Changed-When: Sat, 28 Nov 2015 04:01:12 +0000
State-Changed-Why:
Noted that we already have sem(4) and related man pages. This should be
sufficient to resolve this PR. Waiting feedback from originator.
From: Paul Goyette <paul@vps1.whooppee.com>
To: gnats-bugs@NetBSD.org
Cc: mmondor@pulsar-zone.net
Subject: Re: kern/37427 document _ksem_* syscalls
Date: Sat, 28 Nov 2015 12:01:19 +0800 (PHT)
We currently have man pages for sem(4) with cross-refs to several other
pages for the specific functions.
Is there any reason why this is insufficient? If this is OK, I will
close the PR.
+------------------+--------------------------+-------------------------+
| Paul Goyette | PGP Key fingerprint: | E-mail addresses: |
| (Retired) | FA29 0E3B 35AF E8AE 6651 | paul at whooppee.com |
| Kernel Developer | 0786 F758 55DE 53BA 7731 | pgoyette at netbsd.org |
+------------------+--------------------------+-------------------------+
From: matthew green <mrg@eterna.com.au>
To: gnats-bugs@NetBSD.org
Cc: pgoyette@NetBSD.org, gnats-admin@netbsd.org, netbsd-bugs@netbsd.org,
mmondor@pulsar-zone.net
Subject: re: kern/37427 document _ksem_* syscalls
Date: Sun, 29 Nov 2015 08:02:01 +1100
> We currently have man pages for sem(4) with cross-refs to several other
> pages for the specific functions.
>
> Is there any reason why this is insufficient? If this is OK, I will
> close the PR.
is there documentation on the backend that is sufficient? how is
someone supposed to look at the sem(4) code without understanding
the system calls that back it?
i don't agree that "hidden" functionality should not be documented,
and for actual system calls i don't believe that "in the sources"
suffices.
.mrg.
From: Paul Goyette <paul@vps1.whooppee.com>
To: matthew green <mrg@eterna.com.au>
Cc: gnats-bugs@NetBSD.org, pgoyette@NetBSD.org, gnats-admin@netbsd.org,
netbsd-bugs@netbsd.org, mmondor@pulsar-zone.net
Subject: re: kern/37427 document _ksem_* syscalls
Date: Sun, 29 Nov 2015 06:29:10 +0800 (PHT)
On Sun, 29 Nov 2015, matthew green wrote:
>> We currently have man pages for sem(4) with cross-refs to several other
>> pages for the specific functions.
>>
>> Is there any reason why this is insufficient? If this is OK, I will
>> close the PR.
>
> is there documentation on the backend that is sufficient? how is
> someone supposed to look at the sem(4) code without understanding
> the system calls that back it?
>
> i don't agree that "hidden" functionality should not be documented,
> and for actual system calls i don't believe that "in the sources"
> suffices.
Ah, so in addition to wanting the syscalls themselves documented
(which we have already), you want to see a ksem(9) man page
describing the internal workings?
Let me see if I can do something here... Step 1 - study code ...
+------------------+--------------------------+-------------------------+
| Paul Goyette | PGP Key fingerprint: | E-mail addresses: |
| (Retired) | FA29 0E3B 35AF E8AE 6651 | paul at whooppee.com |
| Kernel Developer | 0786 F758 55DE 53BA 7731 | pgoyette at netbsd.org |
+------------------+--------------------------+-------------------------+
From: Matthew Mondor <mm_lists@pulsar-zone.net>
To: gnats-bugs@NetBSD.org
Cc:
Subject: Re: kern/37427 document _ksem_* syscalls
Date: Sat, 28 Nov 2015 17:40:53 -0500
On Sat, 28 Nov 2015 04:05:00 +0000 (UTC)
Paul Goyette <paul@vps1.whooppee.com> wrote:
> The following reply was made to PR kern/37427; it has been noted by GNATS.
>
> From: Paul Goyette <paul@vps1.whooppee.com>
> To: gnats-bugs@NetBSD.org
> Cc: mmondor@pulsar-zone.net
> Subject: Re: kern/37427 document _ksem_* syscalls
> Date: Sat, 28 Nov 2015 12:01:19 +0800 (PHT)
>
> We currently have man pages for sem(4) with cross-refs to several other
> pages for the specific functions.
>
> Is there any reason why this is insufficient? If this is OK, I will
> close the PR.
Thanks for your concern about this PR.
We indeed have sem(4), linking to the section 3 librt functions,
documenting the public standard interface.
However, the internal syscalls are among the rare exceptions of
undocumented NetBSD syscalls (and therefore lacking their section 2
pages):
_ksem_init(2), _ksem_open(2), _ksem_unlink(2), _ksem_close(2),
_ksem_post(2), _ksem_wait(2), _ksem_trywait(2), _ksem_getvalue(2),
_ksem_destroy(2).
For instance, we have the pthread(3) interface, but also the family of
_lwp_*(2) manual pages.
In my perception, these are like section 9 pages: documentation useful
for the power NetBSD users (a rather large proportion of NetBSD users).
As section 9 pages are useful for kernel developers and auditors,
section 2 man pages are useful to library developers and auditors.
Of course, I realize that this means some work, that I've not myself
done yet either. But an open PR at least helps to remember that these
are still missing.
--
Matt
From: matthew green <mrg@eterna.com.au>
To: paul@whooppee.com
Cc: gnats-bugs@NetBSD.org, pgoyette@NetBSD.org, gnats-admin@netbsd.org,
netbsd-bugs@netbsd.org, mmondor@pulsar-zone.net
Subject: re: kern/37427 document _ksem_* syscalls
Date: Sun, 29 Nov 2015 09:44:44 +1100
> >> We currently have man pages for sem(4) with cross-refs to several other
> >> pages for the specific functions.
> >>
> >> Is there any reason why this is insufficient? If this is OK, I will
> >> close the PR.
> >
> > is there documentation on the backend that is sufficient? how is
> > someone supposed to look at the sem(4) code without understanding
> > the system calls that back it?
> >
> > i don't agree that "hidden" functionality should not be documented,
> > and for actual system calls i don't believe that "in the sources"
> > suffices.
>
> Ah, so in addition to wanting the syscalls themselves documented
> (which we have already), you want to see a ksem(9) man page
> describing the internal workings?
>
> Let me see if I can do something here... Step 1 - study code ...
i don't need ksem(9) exactly -- that could be largely in the
comments in the code. i wouldn't object to it.
it's the user/kernel boundary, even if largely hidden from users,
deserves to be properly documented. it might be documented as
being a backend and point to the normal entry points that should
be used instead.
thanks!
.mrg.
From: Matthew Mondor <mm_lists@pulsar-zone.net>
To: gnats-bugs@NetBSD.org
Cc:
Subject: Re: kern/37427 document _ksem_* syscalls
Date: Sat, 28 Nov 2015 17:50:16 -0500
On Sat, 28 Nov 2015 22:45:01 +0000 (UTC)
Matthew Mondor <mm_lists@pulsar-zone.net> wrote:
> We indeed have sem(4), linking to the section 3 librt functions,
> documenting the public standard interface.
Actually, I'm not really sure why this is in section 4, though.
Possibly because it internally uses a file descriptor?
--
Matt
From: "Paul Goyette" <pgoyette@netbsd.org>
To: gnats-bugs@gnats.NetBSD.org
Cc:
Subject: PR/37427 CVS commit: src
Date: Sun, 29 Nov 2015 06:10:01 +0000
Module Name: src
Committed By: pgoyette
Date: Sun Nov 29 06:10:01 UTC 2015
Modified Files:
src/distrib/sets/lists/comp: mi
src/lib/libc/sys: Makefile.inc
Added Files:
src/lib/libc/sys: _ksem.2
Log Message:
Initial documentation of the internal syscalls that implement the librt
posix semaphores. As requested in PR kern/37427
XXX Feel free to expand this page!
To generate a diff of this commit:
cvs rdiff -u -r1.2007 -r1.2008 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.227 -r1.228 src/lib/libc/sys/Makefile.inc
cvs rdiff -u -r0 -r1.1 src/lib/libc/sys/_ksem.2
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
State-Changed-From-To: feedback->closed
State-Changed-By: pgoyette@NetBSD.org
State-Changed-When: Fri, 05 Feb 2016 05:30:44 +0000
State-Changed-Why:
Initial doc complete.
>Unformatted:
(Contact us)
$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.