NetBSD Problem Report #38979

From www@NetBSD.org  Wed Jun 18 05:21:30 2008
Return-Path: <www@NetBSD.org>
Received: from mail.netbsd.org (mail.netbsd.org [204.152.190.11])
	by narn.NetBSD.org (Postfix) with ESMTP id 495F363B8E3
	for <gnats-bugs@gnats.netbsd.org>; Wed, 18 Jun 2008 05:21:30 +0000 (UTC)
Message-Id: <20080618052130.1EDAF63B842@narn.NetBSD.org>
Date: Wed, 18 Jun 2008 05:21:30 +0000 (UTC)
From: mm_lists@pulsar-zone.net
Reply-To: mm_lists@pulsar-zone.net
To: gnats-bugs@NetBSD.org
Subject: Document syscalls of src/sys/kern/sys_sched.c
X-Send-Pr-Version: www-1.0

>Number:         38979
>Category:       misc
>Synopsis:       Document syscalls of src/sys/kern/sys_sched.c
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    misc-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Wed Jun 18 05:25:00 +0000 2008
>Closed-Date:    
>Last-Modified:  Sun Oct 06 09:47:01 +0000 2013
>Originator:     Matthew Mondor
>Release:        4.99.64
>Organization:
>Environment:
NetBSD sat.xisop 4.99.64 NetBSD 4.99.64 (GENERIC_MM) #0: Thu Jun 12 16:32:06 EDT 2008  root@sat.xisop:/usr/obj/sys/arch/i386/compile/GENERIC_MM i386
>Description:
The following syscalls should be documented via manual pages:

_sched_setparam(2)
_sched_getparam(2)
_sched_setaffinity(2)
_sched_getaffinity(2)
>How-To-Repeat:

>Fix:

>Release-Note:

>Audit-Trail:

State-Changed-From-To: open->closed
State-Changed-By: rmind@NetBSD.org
State-Changed-When: Wed, 18 Jun 2008 08:22:31 +0000
State-Changed-Why:
Have you taken a look at sched(3) and affinity(3) man pages?
Scheduling functions are mostly documented.


From: David Holland <dholland-bugs@netbsd.org>
To: Mindaugas Rasiukevicius <rmind@NetBSD.org>
Cc: Matthew Mondor <mm_lists@pulsar-zone.net>, misc-bug-people@netbsd.org,
	netbsd-bugs@netbsd.org, gnats-bugs@netbsd.org
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

State-Changed-From-To: closed->open
State-Changed-By: dholland@NetBSD.org
State-Changed-When: Sun, 06 Oct 2013 09:47:01 +0000
State-Changed-Why:
Documentation for these syscalls is, as far as I can tell, still missing.


>Unformatted:

Home	PR Database Search