From 00b0426d314829318193693a78f9f9e8af20813b Mon Sep 17 00:00:00 2001 From: julian Date: Fri, 26 Oct 2007 16:50:21 +0000 Subject: Doc police fixes thanks to: ru@ --- share/man/man9/Makefile | 14 +++++-- share/man/man9/kproc.9 | 51 +++++++++++++++---------- share/man/man9/kthread.9 | 96 +++++++++++++++++++++++++++--------------------- 3 files changed, 97 insertions(+), 64 deletions(-) (limited to 'share') diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 093aea9..2175f69 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -129,6 +129,7 @@ MAN= accept_filter.9 \ kernacc.9 \ kernel_mount.9 \ kobj.9 \ + kproc.9 \ kqueue.9 \ kthread.9 \ ktr.9 \ @@ -674,6 +675,13 @@ MLINKS+=kobj.9 DEFINE_CLASS.9 \ kobj.9 kobj_create.9 \ kobj.9 kobj_delete.9 \ kobj.9 kobj_init.9 +MLINKS+=kproc.9 kproc_create.9 \ + kproc.9 kproc_exit.9 \ + kproc.9 kproc_resume,.9 \ + kproc.9 kproc_shutdown.9 \ + kproc.9 kproc_start.9 \ + kproc.9 kproc_suspend.9 \ + kproc.9 kproc_suspend_check.9 MLINKS+=kqueue.9 knlist_add.9 \ kqueue.9 knlist_clear.9 \ kqueue.9 knlist_delete.9 \ @@ -688,11 +696,11 @@ MLINKS+=kqueue.9 knlist_add.9 \ kqueue.9 kqfd_register.9 \ kqueue.9 kqueue_add_filteropts.9 \ kqueue.9 kqueue_del_filteropts.9 -MLINKS+=kthread.9 kproc_shutdown.9 \ - kthread.9 kproc_start.9 \ - kthread.9 kthread_create.9 \ +MLINKS+=kthread.9 kthread_add.9 \ kthread.9 kthread_exit.9 \ kthread.9 kthread_resume.9 \ + kthread.9 kthread_shutdown.9 \ + kthread.9 kthread_start.9 \ kthread.9 kthread_suspend.9 \ kthread.9 kthread_suspend_check.9 MLINKS+=ktr.9 CTR0.9 \ diff --git a/share/man/man9/kproc.9 b/share/man/man9/kproc.9 index 2f82c23..dcede3c1 100644 --- a/share/man/man9/kproc.9 +++ b/share/man/man9/kproc.9 @@ -36,7 +36,7 @@ .Nm kproc_resume , .Nm kproc_suspend , .Nm kproc_suspend_check -.Nd kernel procs +.Nd "kernel processes" .Sh SYNOPSIS .In sys/kthread.h .Ft void @@ -44,7 +44,11 @@ .Ft void .Fn kproc_shutdown "void *arg" "int howto" .Ft int -.Fn kproc_create "void (*func)(void *)" "void *arg" "struct proc **newpp" "int flags" "int pages" "const char *fmt" "..." +.Fo kproc_create +.Fa "void (*func)(void *)" "void *arg" "struct proc **newpp" +.Fa "int flags" "int pages" +.Fa "const char *fmt" ... +.Fc .Ft void .Fn kproc_exit "int ecode" .Ft int @@ -58,37 +62,41 @@ The function .Fn kproc_start is used to start .Dq internal -daemons such as bufdaemon, pagedaemon, vmdaemon, and the syncer and is intended +daemons such as +.Nm bufdaemon , pagedaemon , vmdaemon , +and the +.Nm syncer +and is intended to be called from .Xr SYSINIT 9 . The .Fa udata argument is actually a pointer to a -.Li struct kproc_desc +.Vt "struct kproc_desc" which describes the kernel process that should be created: .Bd -literal -offset indent struct kproc_desc { - char *arg0; - void (*func)(void); - struct proc **global_procpp; + char *arg0; + void (*func)(void); + struct proc **global_procpp; }; .Ed .Pp The structure members are used by .Fn kproc_start as follows: -.Bl -tag -width "global_procpp" -offset indent +.Bl -tag -width ".Va global_procpp" -offset indent .It Va arg0 String to be used for the name of the process. This string will be copied into the .Va p_comm member of the new process' -.Li struct proc . +.Vt "struct proc" . .It Va func The main function for this kernel process to run. .It Va global_procpp A pointer to a -.Li struct proc +.Vt "struct proc" pointer that should be updated to point to the newly created process' process structure. If this variable is @@ -99,7 +107,9 @@ then it is ignored. The .Fn kproc_create function is used to create a kernel process. -The new process shares its address space with process 0, the swapper process, +The new process shares its address space with process 0, the +.Nm swapper +process, and runs in kernel mode only. The .Fa func @@ -112,7 +122,7 @@ when it is called by the new process. The .Fa newpp pointer points to a -.Li struct proc +.Vt "struct proc" pointer that is to be updated to point to the newly created process. If this argument is .Dv NULL , @@ -131,7 +141,7 @@ argument list that is used to build the name of the new process and is stored in the .Va p_comm member of the new process's -.Li struct proc . +.Vt "struct proc" . .Pp The .Fn kproc_exit @@ -170,7 +180,7 @@ resume request. The .Fa p argument points to the -.Li struct proc +.Vt "struct proc" of the kernel process to suspend or resume. For .Fn kproc_suspend , @@ -195,14 +205,14 @@ and functions return zero on success and non-zero on failure. .Sh EXAMPLES This example demonstrates the use of a -.Li struct kproc_desc +.Vt "struct kproc_desc" and the functions .Fn kproc_start , .Fn kproc_shutdown , and .Fn kproc_suspend_check to run the -.Dq bufdaemon +.Nm bufdaemon process. .Bd -literal -offset indent static struct proc *bufdaemonproc; @@ -297,6 +307,9 @@ functions were named .Fn shutdown_kproc , and .Fn kproc_suspend_loop , -respectively. Originally they had the names -.Fn kthread_xxx -but were changed when real kthreads became available. +respectively. +Originally they had the names +.Fn kthread_* +but were changed to +.Fn kproc_* +when real kthreads became available. diff --git a/share/man/man9/kthread.9 b/share/man/man9/kthread.9 index bbb49af..5a8c010 100644 --- a/share/man/man9/kthread.9 +++ b/share/man/man9/kthread.9 @@ -25,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd September 24, 2004 +.Dd October 26, 2007 .Dt KTHREAD 9 .Os .Sh NAME @@ -36,9 +36,7 @@ .Nm kthread_resume , .Nm kthread_suspend , .Nm kthread_suspend_check -.Nd kernel threads -.Pp -.Em PROCESSES . +.Nd "kernel threads" .Sh SYNOPSIS .In sys/kthread.h .Ft void @@ -46,7 +44,11 @@ .Ft void .Fn kthread_shutdown "void *arg" "int howto" .Ft int -.Fn kthread_add "void (*func)(void *)" "void *arg" "struct proc *procp" "struct thread **newtdpp" "int flags" "int pages" "const char *fmt" "..." +.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 @@ -60,51 +62,62 @@ The function .Fn kthread_start is used to start .Dq internal -daemons such as bufdaemon, pagedaemon, vmdaemon, and the syncer and is intended +daemons such as +.Nm bufdaemon , pagedaemon , vmdaemon , +and the +.Nm syncer +and is intended to be called from .Xr SYSINIT 9 . The .Fa udata argument is actually a pointer to a -.Li struct kthread_desc +.Vt "struct kthread_desc" which describes the kernel thread that should be created: .Bd -literal -offset indent struct kthread_desc { - char *arg0; - void (*func)(void); - struct thread **global_threadpp; + char *arg0; + void (*func)(void); + struct thread **global_threadpp; }; .Ed .Pp The structure members are used by .Fn kthread_start as follows: -.Bl -tag -width "global_threadpp" -offset indent +.Bl -tag -width ".Va global_threadpp" -offset indent .It Va arg0 String to be used for the name of the thread. This string will be copied into the .Va td_name member of the new threads' -.Li struct thread . +.Vt "struct thread" . .It Va func -The main function for this kernel process to run. +The main function for this kernel thread to run. .It Va global_threadpp A pointer to a -.Li struct thread -pointer that should be updated to point to the newly created thread' thread +.Vt "struct thread" +pointer that should be updated to point to the newly created thread's +.Vt thread structure. If this variable is .Dv NULL , -then it is ignored. The thread will be a subthread of proc0 (PID 0). +then it is ignored. +The thread will be a subthread of +.Va proc0 +(PID 0). .El .Pp The .Fn kthread_add function is used to create a kernel thread. -The new thread runs in kernel mode only. It is added to the -process specified by the +The new thread runs in kernel mode only. +It is added to the process specified by the .Fa procp -argument, or if that is NULL, to proc0. +argument, or if that is +.Dv NULL , +to +.Va proc0 . The .Fa func argument specifies the function that the thread should execute. @@ -112,11 +125,11 @@ The .Fa arg argument is an arbitrary pointer that is passed in as the only argument to .Fa func -when it is called by the new process. +when it is called by the new thread. The -.Fa newtdp +.Fa newtdpp pointer points to a -.Li struct thread +.Vt "struct thread" pointer that is to be updated to point to the newly created thread. If this argument is .Dv NULL , @@ -135,14 +148,14 @@ argument list that is used to build the name of the new thread and is stored in the .Va td_name member of the new thread's -.Li struct thread . +.Vt "struct thread" . .Pp The .Fn kthread_exit function is used to terminate kernel threads. It should be called by the main function of the kernel thread rather than letting the main function return to its caller. -The +.\" XXX "int ecode" argument isn't documented. .Pp The .Fn kthread_resume , @@ -167,7 +180,7 @@ resume request. The .Fa td argument points to the -.Li struct thread +.Vt "struct thread" of the kernel thread to suspend or resume. For .Fn kthread_suspend , @@ -192,14 +205,14 @@ and functions return zero on success and non-zero on failure. .Sh EXAMPLES This example demonstrates the use of a -.Li struct kthread_desc +.Vt "struct kthread_desc" and the functions .Fn kthread_start , .Fn kthread_shutdown , and .Fn kthread_suspend_check to run the -.Dq bufdaemon +.Nm bufdaemon process. .Bd -literal -offset indent static struct thread *bufdaemonthread; @@ -242,7 +255,7 @@ argument does not reference a kernel thread. .El .Pp The -.Fn kthread_create +.Fn kthread_add function will fail if: .Bl -tag -width Er .It Bq Er EAGAIN @@ -261,39 +274,38 @@ parameter. .El .Sh SEE ALSO .Xr rfork 2 , -.Xr kproc 9 , .Xr exit1 9 , +.Xr kproc 9 , .Xr SYSINIT 9 , .Xr wakeup 9 .Sh HISTORY The .Fn kthread_start function first appeared in -.Fx 2.2 -where it created a whole process. It was converted to create threads in +.Fx 2.2 +where it created a whole process. +It was converted to create threads in .Fx 8.0 . The .Fn kthread_shutdown , -.Fn kthread_create , .Fn kthread_exit , .Fn kthread_resume , .Fn kthread_suspend , and .Fn kthread_suspend_check functions were introduced in -.Fx 4.0 -and were converted to treads in +.Fx 4.0 +and were converted to threads in .Fx 8.0 . -The +The .Fn kthread_create -call was renamed to kthread_add in +call was renamed to +.Fn kthread_add +in .Fx 8.0 . -The old functionality of creating a kernel process was renamed -to -.Fn kproc_create -(and friends). -See -.Xr kproc 9 +The old functionality of creating a kernel process was renamed +to +.Xr kproc_create 9 . Prior to .Fx 5.0 , the -- cgit v1.1