From nobody@FreeBSD.org  Sun Aug  3 23:07:28 2008
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 31B10106564A
	for <freebsd-gnats-submit@FreeBSD.org>; Sun,  3 Aug 2008 23:07:28 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (www.freebsd.org [IPv6:2001:4f8:fff6::21])
	by mx1.freebsd.org (Postfix) with ESMTP id 1DCA98FC08
	for <freebsd-gnats-submit@FreeBSD.org>; Sun,  3 Aug 2008 23:07:28 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.14.2/8.14.2) with ESMTP id m73N7RqH051993
	for <freebsd-gnats-submit@FreeBSD.org>; Sun, 3 Aug 2008 23:07:27 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.14.2/8.14.1/Submit) id m73N7RPl051992;
	Sun, 3 Aug 2008 23:07:27 GMT
	(envelope-from nobody)
Message-Id: <200808032307.m73N7RPl051992@www.freebsd.org>
Date: Sun, 3 Aug 2008 23:07:27 GMT
From: Mateusz Guzik <mjguzik@gmail.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: [patch] kthread(9) refers to non-existent manpage, describes invalid return values
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         126227
>Category:       docs
>Synopsis:       [patch] kthread(9) refers to non-existent manpage, describes invalid return values
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sun Aug 03 23:10:00 UTC 2008
>Closed-Date:    Sat Jul 21 15:48:43 UTC 2012
>Last-Modified:  Sat Jul 21 15:48:43 UTC 2012
>Originator:     Mateusz Guzik
>Release:        8.0-CURRENT
>Organization:
>Environment:
FreeBSD eternal 8.0-CURRENT FreeBSD 8.0-CURRENT #24: Wed Jul 23 01:21:38 CEST 2008     f@eternal:/usr/obj/usr/src/sys/ETERNAL  i386

>Description:
I've found a bunch of problems:
- values that can be used in the flags argument for khtread_add are declared in sys/unistd.h, so I believe that file should be mentioned
- the only supported flag is RFSTOPPED, which is not described in rfork(2) (as it's kernel-only)
- If I understand kthread_add correctly, the only case of failure returns ENOMEM

- this manpage refers to non-existent exit1(9)

>How-To-Repeat:

>Fix:
Proposed patch is attached.

Patch attached with submission follows:

--- share/man/man9/kthread.9.orig	2008-08-03 23:43:40.000000000 +0200
+++ share/man/man9/kthread.9	2008-08-03 23:59:22.000000000 +0200
@@ -23,11 +23,11 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
 .\" $FreeBSD: src/share/man/man9/kthread.9,v 1.18 2008/04/29 22:43:15 julian Exp $
 .\"
-.Dd October 26, 2007
+.Dd August 3, 2008
 .Dt KTHREAD 9
 .Os
 .Sh NAME
 .Nm kthread_start ,
 .Nm kthread_shutdown ,
@@ -41,24 +41,25 @@
 .In sys/kthread.h
 .Ft void
 .Fn kthread_start "const void *udata"
 .Ft void
 .Fn kthread_shutdown "void *arg" "int howto"
-.Ft int
-.Fo kthread_add
-.Fa "void (*func)(void *)" "void *arg" "struct proc *procp"
-.Fa "struct thread **newtdpp" "int flags" "int pages"
-.Fa "const char *fmt" ...
-.Fc
 .Ft void
 .Fn kthread_exit "void"
 .Ft int
 .Fn kthread_resume "struct thread *td"
 .Ft int
 .Fn kthread_suspend "struct thread *td" "int timo"
 .Ft void
 .Fn kthread_suspend_check "struct thread *td"
+.In sys/unistd.h
+.Ft int
+.Fo kthread_add
+.Fa "void (*func)(void *)" "void *arg" "struct proc *procp"
+.Fa "struct thread **newtdpp" "int flags" "int pages"
+.Fa "const char *fmt" ...
+.Fc
 .Ft int
 .Fo kproc_kthread_add
 .Fa "void (*func)(void *)" "void *arg"
 .Fa "struct proc **procptr" "struct thread **tdptr"
 .Fa "int flags" "int pages" "char * procname" "const char *fmt" "..."
@@ -140,12 +141,11 @@
 If this argument is
 .Dv NULL ,
 then it is ignored.
 The
 .Fa flags
-argument specifies a set of flags as described in
-.Xr rfork 2 .
+argument can be set to RFSTOPPED, to leave thread in a stopped state.
 The
 .Fa pages
 argument specifies the size of the new kernel thread's stack in pages.
 If 0 is used, the default kernel stack size is allocated.
 The rest of the arguments form a
@@ -272,27 +272,14 @@
 .Pp
 The
 .Fn kthread_add
 function will fail if:
 .Bl -tag -width Er
-.It Bq Er EAGAIN
-The system-imposed limit on the total
-number of processes under execution would be exceeded.
-The limit is given by the
-.Xr sysctl 3
-MIB variable
-.Dv KERN_MAXPROC .
-.It Bq Er EINVAL
-The
-.Dv RFCFDG
-flag was specified in the
-.Fa flags
-parameter.
+.It Bq Er ENOMEM
+Memmory for thread's stack couldn't be allocated.
 .El
 .Sh SEE ALSO
-.Xr rfork 2 ,
-.Xr exit1 9 ,
 .Xr kproc 9 ,
 .Xr SYSINIT 9 ,
 .Xr wakeup 9
 .Sh HISTORY
 The


>Release-Note:
>Audit-Trail:
State-Changed-From-To: open->patched 
State-Changed-By: trhodes 
State-Changed-When: Tue Jan 27 00:23:57 UTC 2009 
State-Changed-Why:  
Different version of your patch committed to HEAD, thanks 
for the submission! 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Tue Jan 27 00:23:57 UTC 2009 
Responsible-Changed-Why:  
Over to me. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=126227 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/126227: commit references a PR
Date: Tue, 27 Jan 2009 00:22:47 +0000 (UTC)

 Author: trhodes
 Date: Tue Jan 27 00:22:16 2009
 New Revision: 187746
 URL: http://svn.freebsd.org/changeset/base/187746
 
 Log:
   Add ENOMEM to the return values.
   Remove invalid return values.
   Remove reference to non-existent manual pages.
   Remove reference to rfork (it does not discuss RFSTOPPED).
   Add sys/unistd.h to the list of includes (required for RFSTOPPED).
   
   PR:		126227
   Submitted by:	Mateusz Guzik <mjguzik@gmail.com> (based on, original version)
   Reviewed by:	jhb, Christoph Mallon <christoph.mallon@gmx.de>
 
 Modified:
   head/share/man/man9/kthread.9
 
 Modified: head/share/man/man9/kthread.9
 ==============================================================================
 --- head/share/man/man9/kthread.9	Mon Jan 26 23:17:19 2009	(r187745)
 +++ head/share/man/man9/kthread.9	Tue Jan 27 00:22:16 2009	(r187746)
 @@ -25,7 +25,7 @@
  .\"
  .\" $FreeBSD$
  .\"
 -.Dd October 26, 2007
 +.Dd January 26, 2009
  .Dt KTHREAD 9
  .Os
  .Sh NAME
 @@ -43,12 +43,6 @@
  .Fn kthread_start "const void *udata"
  .Ft void
  .Fn kthread_shutdown "void *arg" "int howto"
 -.Ft int
 -.Fo kthread_add
 -.Fa "void (*func)(void *)" "void *arg" "struct proc *procp"
 -.Fa "struct thread **newtdpp" "int flags" "int pages"
 -.Fa "const char *fmt" ...
 -.Fc
  .Ft void
  .Fn kthread_exit "void"
  .Ft int
 @@ -57,6 +51,13 @@
  .Fn kthread_suspend "struct thread *td" "int timo"
  .Ft void
  .Fn kthread_suspend_check "struct thread *td"
 +.In sys/unistd.h
 +.Ft int
 +.Fo kthread_add
 +.Fa "void (*func)(void *)" "void *arg" "struct proc *procp"
 +.Fa "struct thread **newtdpp" "int flags" "int pages"
 +.Fa "const char *fmt" ...
 +.Fc
  .Ft int
  .Fo kproc_kthread_add
  .Fa "void (*func)(void *)" "void *arg"
 @@ -142,8 +143,12 @@ If this argument is
  then it is ignored.
  The
  .Fa flags
 -argument specifies a set of flags as described in
 -.Xr rfork 2 .
 +argument may be set to
 +.Dv RFSTOPPED
 +to leave the thread in a stopped state.
 +The caller must call
 +.Fn sched_add
 +to start the thread.
  The
  .Fa pages
  argument specifies the size of the new kernel thread's stack in pages.
 @@ -274,23 +279,10 @@ The
  .Fn kthread_add
  function will fail if:
  .Bl -tag -width Er
 -.It Bq Er EAGAIN
 -The system-imposed limit on the total
 -number of processes under execution would be exceeded.
 -The limit is given by the
 -.Xr sysctl 3
 -MIB variable
 -.Dv KERN_MAXPROC .
 -.It Bq Er EINVAL
 -The
 -.Dv RFCFDG
 -flag was specified in the
 -.Fa flags
 -parameter.
 +.It Bq Er ENOMEM
 +Memory for a thread's stack could not be allocated.
  .El
  .Sh SEE ALSO
 -.Xr rfork 2 ,
 -.Xr exit1 9 ,
  .Xr kproc 9 ,
  .Xr SYSINIT 9 ,
  .Xr wakeup 9
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: patched->closed 
State-Changed-By: trhodes 
State-Changed-When: Sat Jul 21 15:48:22 UTC 2012 
State-Changed-Why:  
Changes have been merged for awhile now, thanks. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=126227 
>Unformatted:
