Re: kern/37427 document _ksem_* syscalls

[Matthew Mondor <mm_lists%pulsar-zone.net@localhost>]

The following reply was made to PR kern/37427; it has been noted by GNATS.

From: Matthew Mondor <mm_lists%pulsar-zone.net@localhost>
To: gnats-bugs%NetBSD.org@localhost
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@localhost> wrote:
 
 > The following reply was made to PR kern/37427; it has been noted by GNATS.
 > 
 > From: Paul Goyette <paul%vps1.whooppee.com@localhost>
 > To: gnats-bugs%NetBSD.org@localhost
 > Cc: mmondor%pulsar-zone.net@localhost
 > 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