Re: misc/38979 (Document syscalls of src/sys/kern/sys_sched.c)

[David Holland <dholland-bugs%netbsd.org@localhost>]

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

From: David Holland <dholland-bugs%netbsd.org@localhost>
To: Mindaugas Rasiukevicius <rmind%NetBSD.org@localhost>
Cc: Matthew Mondor <mm_lists%pulsar-zone.net@localhost>, 
misc-bug-people%netbsd.org@localhost,
        netbsd-bugs%netbsd.org@localhost, gnats-bugs%netbsd.org@localhost
Subject: Re: misc/38979 (Document syscalls of src/sys/kern/sys_sched.c)
Date: Tue, 24 Mar 2009 22:11:57 +0000

 On Wed, Jun 18, 2008 at 08:14:33PM +0100, Mindaugas Rasiukevicius wrote:
  > > ... Note that sched(3) describes the librt POSIX
  > > API (section 3) while the syscalls work on LWPs and should be
  > > documented in section 2, IMO.
  > 
  > I am not sure if this is a good idea. These syscalls are internal, and
  > should not be used by user. In other words - user should not know anything
  > about them.
  > 
  > There are actually more internal syscalls, and seems _lwp_* are the only
  > exception, when they are documented. Hmm..
 
 All the internal syscalls should be documented, because application
 developers are not the only consumer (or probably even the primary
 consumer) of documentation for obscure syscalls. People working on
 libc or the kernel or on binary compat are.
 
 If you're concerned about people thinking they should use them
 directly, we can put text in the man page saying "this is an internal
 interface; application software should use the sched(3) API" or
 equivalent. (Anyone who ignores such warnings deserves the
 consequences.)
 
 -- 
 David A. Holland
 dholland%netbsd.org@localhost