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:

NetBSD Home
NetBSD PR Database Search

(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.