docs/126227: [patch] kthread(9) refers to non-existent manpage, describes invalid return values

[Mateusz Guzik]

>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:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sun Aug 03 23:10:00 UTC 2008
>Closed-Date:
>Last-Modified:
>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 at 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:
>Unformatted: