better, nicer, neater documentation

2 files changed, 290 insertions, 160 deletions

diff --git a/lib/libc_r/man/pthreads.3 b/lib/libc_r/man/pthreads.3
index 055033a8dd9..b42a627c6e6 100644
--- a/lib/libc_r/man/pthreads.3
+++ b/lib/libc_r/man/pthreads.3
@@ -1,86 +1,120 @@
+.\" $OpenBSD: pthreads.3,v 1.3 1999/03/22 04:21:45 d Exp $
+.\" David Leonard <d@openbsd.org>, 1998. Public domain.
 .Dd August 17, 1998
 .Dt PTHREADS 3
 .Os BSD 4
 .Sh NAME
 .Nm pthreads
 .Nd POSIX 1003.1c thread interface
-.Sh SYNOPSIS
-.Fd #include <pthread.h>
-.Ft int
-.Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg"
-.Ft void
-.Fn pthread_cleanup_pop "int execute"
-.Ft void
-.Fn pthread_cleanup_push "void (*cleanup_routine)(void *)" "void *arg"
-.Ft int
-.Fn pthread_cond_broadcast "pthread_cond_t *cond"
-.Ft int
-.Fn pthread_cond_destroy "pthread_cond_t *cond"
-.Ft int
-.Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr"
-.Ft int
-.Fn pthread_cond_signal "pthread_cond_t *cond"
-.Ft int
-.Fn pthread_cond_timedwait "pthread_cond_t *cond" "pthread_mutex_t *mutex" "const struct timespec *abstime"
-.Ft int
-.Fn pthread_cond_wait "pthread_cond_t *cond" "pthread_mutex_t *mutex"
-.Ft int
-.Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg"
-.Fn pthread_exit
-.Ft int
-.Fn pthread_detach "pthread_t thread"
-.Ft int
-.Fn pthread_equal "pthread_t t1" "pthread_t t2"
-.Ft void
-.Fn pthread_exit "void *value_ptr"
-.Ft void *
-.Fn pthread_getspecific "pthread_key_t key"
-.Ft int
-.Fn pthread_join "pthread_t thread" "void **value_ptr"
-.Ft int
-.Fn pthread_key_create "pthread_key_t *key" "void (*destructor)(void *)"
-.Ft int
-.Fn pthread_key_delete "pthread_key_t key"
-.Ft int
-.Fn pthread_mutex_destroy "pthread_mutex_t *mutex"
-.Ft int
-.Fn pthread_mutex_init "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr"
-.Ft int
-.Fn pthread_mutex_lock "pthread_mutex_t *mutex"
-.Ft int
-.Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
-.Ft int
-.Fn pthread_mutex_unlock "pthread_mutex_t *mutex"
-.Ft int
-.Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)"
-.Ft int
-.Fn pthread_rwlock_destroy "pthread_rwlock_t *lock"
-.Ft int
-.Fn pthread_rwlock_init "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr"
-.Ft int
-.Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock"
-.Ft int
-.Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock"
-.Ft int
-.Fn pthread_rwlock_unlock "pthread_rwlock_t *lock"
-.Ft int
-.Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock"
-.Ft int
-.Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock"
-.Ft int
-.Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr"
-.Ft int
-.Fn pthread_rwlockattr_getpshared "pthread_rwlockattr_t *attr" "int *pshared"
-.Ft int
-.Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr"
-.Ft int
-.Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int *pshared"
-.Ft pthread_t
-.Fn pthread_self "void"
-.Ft int
-.Fn pthread_setspecific "pthread_key_t key" "const void *value"
 .Sh DESCRIPTION
-Steal something from the posix specs to describe what a thread is.
+A thread is a flow of control within a process.
+Each thread represents a minimal amount of state;
+normally just the cpu state and a signal mask.
+All other process state (such as memory, file descriptors)
+is shared among all of the threads in the process.
+.Pp
+In
+.Ox ,
+threads are implemented in a user-level library
+.Pa ( libc_r )
+that replaces the standard C library
+.Pa ( libc ) .
+This replacement is currently achieved by specifying the
+.Fl pthread
+flag to
+.Xr cc 1
+for each compilation unit, and for linking.
+(But see the section on
+.Sx BUGS . )
+.Pp
+The
+.Dv SIGINFO
+signal can be sent to a threaded process to have the library show the state of
+all of its threads. The information is sent to the process'
+.Pa /dev/tty .
+.Pp
+Threads can be in one of these states:
+.Bl -tag -offset indent -width Dv -compact
+.It cond_wait
+Executing
+.Xr pthread_cond_wait 3
+or
+.Xr pthread_cond_timedwait 3 .
+.It dead
+Waiting for resource deallocation by the thread garbage collector.
+.It fdlr_wait
+File descriptor read lock wait.
+.It fdlw_wait
+File descriptor write lock wait.
+.It fdr_wait
+Executing one of
+.Xr accept 2 ,
+.Xr read 2 ,
+.Xr readv 2 ,
+.Xr recvfrom 2 ,
+.Xr recvmsg 2 .
+.It fdw_wait
+Executing one of
+.Xr connect 2 ,
+.Xr sendmsg 2 ,
+.Xr sendto 2 ,
+.Xr write 2 ,
+.Xr writev 2 .
+.It file_wait
+Executing
+.Xr flockfile 3
+or similar.
+.It join
+Executing
+.Xr pthread_join 3 .
+.It mutex_wait
+Executing
+.Xr pthread_mutex_lock 3 .
+.It running
+Scheduled for, or engaged in, program execution.
+.It select_wait
+Executing
+.Xr select 2 .
+.It sigsuspend
+Executing
+.Xr sigsuspend 2 .
+.It sigwait
+Executing
+.Xr sigwait 3 .
+.It sleep_wait
+Executing
+.Xr sleep 3
+or
+.Xr nanosleep 2 .
+.It suspended
+Suspended with
+.Xr pthread_suspend_np 3 .
+.It wait_wait
+Executing
+.Xr wait4 2
+or similar.
+.El
+.Ss Scheduling algorithm
+The scheduling algorithm used by the user-level thread library is
+roughly as follows:
+.Bl -enum -compact
+.It
+Threads each have a time slice credit which is debited
+by the actual time the thread spends in running.
+Freshly scheduled threads are given a time slice credit of 100000 usec.
+.It
+Give an incremental priority update to run-enabled threads that
+have not run since the last time that an incremental priority update
+was given to them.
+.It
+Choose the next run-enabled thread with the highest priority,
+that became inactive least recently, and has
+the largest remaining time slice.
+.El
+.Pp
+When all threads are blocked, the process also blocks.
+When there are no threads remaining,
+the process terminates with an exit code of zero.
 .Sh SEE ALSO
 .Xr pthread_cleanup_pop 3 ,
 .Xr pthread_cleanup_push 3 ,
@@ -106,7 +140,7 @@ Steal something from the posix specs to describe what a thread is.
 .Xr pthread_once 3 ,
 .Xr pthread_rwlock_destroy 3 ,
 .Xr pthread_rwlock_init 3 ,
-.Xr pthread_rwlock_rdlock.3 
+.Xr pthread_rwlock_rdlock 3 ,
 .Xr pthread_rwlock_unlock 3 ,
 .Xr pthread_rwlock_wrlock 3 ,
 .Xr pthread_rwlockattr_destroy 3 ,
@@ -114,9 +148,40 @@ Steal something from the posix specs to describe what a thread is.
 .Xr pthread_rwlockattr_init 3 ,
 .Xr pthread_rwlockattr_setpshared 3 ,
 .Xr pthread_self 3 ,
-.Xr pthread_setspecific 3 
+.Xr pthread_setspecific 3
 .Sh STANDARDS
-.Fn pthread_create
-conforms to ISO/IEC 9945-1 ANSI/IEEE
+The user-level thread library provides functions that
+conform to ISO/IEC 9945-1 ANSI/IEEE
 .Pq Dq Tn POSIX
 Std 1003.1 Second Edition 1996-07-12.
+.Sh AUTHORS
+John Birrell
+.Pa ( jb@freebsd.org )
+wrote the majority of the user level thread library.
+.\" David Leonard did a fair bit too, but is far too modest.
+.Sh BUGS
+Having to pass the
+.Fl pthread
+flag to
+.Xr cc 1
+for every compilation unit and linking is an awful kludge.
+Future releases will most likely depreceate this flag,
+and instead only use
+.Fl l Ns Pa pthread
+during linking.
+.Pp
+The library contains of a scheduler that uses the
+process virtual interval timer to pre-empt running threads.
+This means that using
+.Xr setitimer 2
+to alter the process virtual timer will have undefined effects. The
+.Dv SIGVTALRM
+will never be delivered to threads in a process.
+.Pp
+Due to the 
+type definition of
+.Ft fd_set
+and the internal reliance on
+.Xr select 2 ,
+threaded processes may be arbitrarily limited in the number of file descriptors
+that they can collectively have open.
diff --git a/lib/libpthread/man/pthreads.3 b/lib/libpthread/man/pthreads.3
index 055033a8dd9..b42a627c6e6 100644
--- a/lib/libpthread/man/pthreads.3
+++ b/lib/libpthread/man/pthreads.3
@@ -1,86 +1,120 @@
+.\" $OpenBSD: pthreads.3,v 1.3 1999/03/22 04:21:45 d Exp $
+.\" David Leonard <d@openbsd.org>, 1998. Public domain.
 .Dd August 17, 1998
 .Dt PTHREADS 3
 .Os BSD 4
 .Sh NAME
 .Nm pthreads
 .Nd POSIX 1003.1c thread interface
-.Sh SYNOPSIS
-.Fd #include <pthread.h>
-.Ft int
-.Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg"
-.Ft void
-.Fn pthread_cleanup_pop "int execute"
-.Ft void
-.Fn pthread_cleanup_push "void (*cleanup_routine)(void *)" "void *arg"
-.Ft int
-.Fn pthread_cond_broadcast "pthread_cond_t *cond"
-.Ft int
-.Fn pthread_cond_destroy "pthread_cond_t *cond"
-.Ft int
-.Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr"
-.Ft int
-.Fn pthread_cond_signal "pthread_cond_t *cond"
-.Ft int
-.Fn pthread_cond_timedwait "pthread_cond_t *cond" "pthread_mutex_t *mutex" "const struct timespec *abstime"
-.Ft int
-.Fn pthread_cond_wait "pthread_cond_t *cond" "pthread_mutex_t *mutex"
-.Ft int
-.Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg"
-.Fn pthread_exit
-.Ft int
-.Fn pthread_detach "pthread_t thread"
-.Ft int
-.Fn pthread_equal "pthread_t t1" "pthread_t t2"
-.Ft void
-.Fn pthread_exit "void *value_ptr"
-.Ft void *
-.Fn pthread_getspecific "pthread_key_t key"
-.Ft int
-.Fn pthread_join "pthread_t thread" "void **value_ptr"
-.Ft int
-.Fn pthread_key_create "pthread_key_t *key" "void (*destructor)(void *)"
-.Ft int
-.Fn pthread_key_delete "pthread_key_t key"
-.Ft int
-.Fn pthread_mutex_destroy "pthread_mutex_t *mutex"
-.Ft int
-.Fn pthread_mutex_init "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr"
-.Ft int
-.Fn pthread_mutex_lock "pthread_mutex_t *mutex"
-.Ft int
-.Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
-.Ft int
-.Fn pthread_mutex_unlock "pthread_mutex_t *mutex"
-.Ft int
-.Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)"
-.Ft int
-.Fn pthread_rwlock_destroy "pthread_rwlock_t *lock"
-.Ft int
-.Fn pthread_rwlock_init "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr"
-.Ft int
-.Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock"
-.Ft int
-.Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock"
-.Ft int
-.Fn pthread_rwlock_unlock "pthread_rwlock_t *lock"
-.Ft int
-.Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock"
-.Ft int
-.Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock"
-.Ft int
-.Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr"
-.Ft int
-.Fn pthread_rwlockattr_getpshared "pthread_rwlockattr_t *attr" "int *pshared"
-.Ft int
-.Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr"
-.Ft int
-.Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int *pshared"
-.Ft pthread_t
-.Fn pthread_self "void"
-.Ft int
-.Fn pthread_setspecific "pthread_key_t key" "const void *value"
 .Sh DESCRIPTION
-Steal something from the posix specs to describe what a thread is.
+A thread is a flow of control within a process.
+Each thread represents a minimal amount of state;
+normally just the cpu state and a signal mask.
+All other process state (such as memory, file descriptors)
+is shared among all of the threads in the process.
+.Pp
+In
+.Ox ,
+threads are implemented in a user-level library
+.Pa ( libc_r )
+that replaces the standard C library
+.Pa ( libc ) .
+This replacement is currently achieved by specifying the
+.Fl pthread
+flag to
+.Xr cc 1
+for each compilation unit, and for linking.
+(But see the section on
+.Sx BUGS . )
+.Pp
+The
+.Dv SIGINFO
+signal can be sent to a threaded process to have the library show the state of
+all of its threads. The information is sent to the process'
+.Pa /dev/tty .
+.Pp
+Threads can be in one of these states:
+.Bl -tag -offset indent -width Dv -compact
+.It cond_wait
+Executing
+.Xr pthread_cond_wait 3
+or
+.Xr pthread_cond_timedwait 3 .
+.It dead
+Waiting for resource deallocation by the thread garbage collector.
+.It fdlr_wait
+File descriptor read lock wait.
+.It fdlw_wait
+File descriptor write lock wait.
+.It fdr_wait
+Executing one of
+.Xr accept 2 ,
+.Xr read 2 ,
+.Xr readv 2 ,
+.Xr recvfrom 2 ,
+.Xr recvmsg 2 .
+.It fdw_wait
+Executing one of
+.Xr connect 2 ,
+.Xr sendmsg 2 ,
+.Xr sendto 2 ,
+.Xr write 2 ,
+.Xr writev 2 .
+.It file_wait
+Executing
+.Xr flockfile 3
+or similar.
+.It join
+Executing
+.Xr pthread_join 3 .
+.It mutex_wait
+Executing
+.Xr pthread_mutex_lock 3 .
+.It running
+Scheduled for, or engaged in, program execution.
+.It select_wait
+Executing
+.Xr select 2 .
+.It sigsuspend
+Executing
+.Xr sigsuspend 2 .
+.It sigwait
+Executing
+.Xr sigwait 3 .
+.It sleep_wait
+Executing
+.Xr sleep 3
+or
+.Xr nanosleep 2 .
+.It suspended
+Suspended with
+.Xr pthread_suspend_np 3 .
+.It wait_wait
+Executing
+.Xr wait4 2
+or similar.
+.El
+.Ss Scheduling algorithm
+The scheduling algorithm used by the user-level thread library is
+roughly as follows:
+.Bl -enum -compact
+.It
+Threads each have a time slice credit which is debited
+by the actual time the thread spends in running.
+Freshly scheduled threads are given a time slice credit of 100000 usec.
+.It
+Give an incremental priority update to run-enabled threads that
+have not run since the last time that an incremental priority update
+was given to them.
+.It
+Choose the next run-enabled thread with the highest priority,
+that became inactive least recently, and has
+the largest remaining time slice.
+.El
+.Pp
+When all threads are blocked, the process also blocks.
+When there are no threads remaining,
+the process terminates with an exit code of zero.
 .Sh SEE ALSO
 .Xr pthread_cleanup_pop 3 ,
 .Xr pthread_cleanup_push 3 ,
@@ -106,7 +140,7 @@ Steal something from the posix specs to describe what a thread is.
 .Xr pthread_once 3 ,
 .Xr pthread_rwlock_destroy 3 ,
 .Xr pthread_rwlock_init 3 ,
-.Xr pthread_rwlock_rdlock.3 
+.Xr pthread_rwlock_rdlock 3 ,
 .Xr pthread_rwlock_unlock 3 ,
 .Xr pthread_rwlock_wrlock 3 ,
 .Xr pthread_rwlockattr_destroy 3 ,
@@ -114,9 +148,40 @@ Steal something from the posix specs to describe what a thread is.
 .Xr pthread_rwlockattr_init 3 ,
 .Xr pthread_rwlockattr_setpshared 3 ,
 .Xr pthread_self 3 ,
-.Xr pthread_setspecific 3 
+.Xr pthread_setspecific 3
 .Sh STANDARDS
-.Fn pthread_create
-conforms to ISO/IEC 9945-1 ANSI/IEEE
+The user-level thread library provides functions that
+conform to ISO/IEC 9945-1 ANSI/IEEE
 .Pq Dq Tn POSIX
 Std 1003.1 Second Edition 1996-07-12.
+.Sh AUTHORS
+John Birrell
+.Pa ( jb@freebsd.org )
+wrote the majority of the user level thread library.
+.\" David Leonard did a fair bit too, but is far too modest.
+.Sh BUGS
+Having to pass the
+.Fl pthread
+flag to
+.Xr cc 1
+for every compilation unit and linking is an awful kludge.
+Future releases will most likely depreceate this flag,
+and instead only use
+.Fl l Ns Pa pthread
+during linking.
+.Pp
+The library contains of a scheduler that uses the
+process virtual interval timer to pre-empt running threads.
+This means that using
+.Xr setitimer 2
+to alter the process virtual timer will have undefined effects. The
+.Dv SIGVTALRM
+will never be delivered to threads in a process.
+.Pp
+Due to the 
+type definition of
+.Ft fd_set
+and the internal reliance on
+.Xr select 2 ,
+threaded processes may be arbitrarily limited in the number of file descriptors
+that they can collectively have open.