Submitted by: John Birrell <cimaxp1!jb@werple.net.au>

Here are the diffs for libc_r to get it one step closer to P1003.1c
These make most of the thread/mutex/condvar structures opaque to the
user. There are three functions which have been renamed with _np
suffixes because they are extensions to P1003.1c (I did them for JAVA,
which needs to suspend/resume threads and also start threads suspended).

I've created a new header (pthread_np.h) for the non-POSIX stuff.

The egrep tags stuff in /usr/src/lib/libc_r/Makefile that I uncommented
doesn't work. I think its best to delete it. I don't think libc_r needs
tags anyway, 'cause most of the source is in libc which does have tags.

also:

Here's the first batch of man pages for the thread functions.
The diff to /usr/src/lib/libc_r/Makefile removes some stuff that was
inherited from /usr/src/lib/libc/Makefile that should only be done with
libc.

also:

I should have sent this diff with the pthread(3) man page.
It allows people to type

make -DWANT_LIBC_R world

to get libc_r built with the rest of the world. I put this in the
pthread(3) man page.  The default is still not to build libc_r.


also:
The diff attached adds a pthread(3) man page to /usr/src/share/man/man3.
The idea is that without libc_r installed, this man page will give people
enough info to know that they have to build libc_r.

1 files changed, 214 insertions, 0 deletions

diff --git a/share/man/man3/pthread.3 b/share/man/man3/pthread.3
new file mode 100644
index 0000000..5e2e24c
--- /dev/null
+++ b/share/man/man3/pthread.3
@@ -0,0 +1,214 @@
+.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by John Birrell.
+.\" 4. Neither the name of the author nor the names of any co-contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd April 4, 1996
+.Dt PTHREAD 3
+.Os BSD 4
+.Sh NAME
+.Nm pthread
+.Nd POSIX thread functions
+.Sh DESCRIPTION
+POSIX threads are a set of functions that support applications with
+requirements for multiple flows of control, called
+.Fa threads ,
+within a process. Multithreading is used to improve the performance of a
+program.
+.Pp
+The POSIX thread functions are summarized in this section in the following
+groups:
+.Bl -bullet -offset indent
+.It
+Thread routines
+.It
+Attribute Object Routines
+.It
+Mutex Routines
+.It
+Condition Variable Routines
+.It
+Per-Thread Context Routines
+.It
+Cleanup Routines
+.El
+.Sh THREAD ROUTINES
+.Bl -tag -width Er
+.It int Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg"
+Creates a new thread of execution.
+.It int Fn pthread_detach "pthread_t thread"
+Marks a thread for deletion.
+.It int Fn pthread_equal "pthread_t t1" "pthread_t t2"
+Compares two thread IDs.
+.It void Fn pthread_exit "void *value_ptr"
+Terminates the calling thread.
+.It int Fn pthread_join "pthread_t thread" "void **value_ptr"
+Causes the calling thread to wait for the termination of the specified thread.
+.It int Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)"
+Calls an initialization routine once.
+.It pthread_t Fn pthread_self void
+Returns the thread ID of the calling thread.
+.El
+.Sh ATTRIBUTE OBJECT ROUTINES
+.Bl -tag -width Er
+.It int Fn pthread_attr_destroy "pthread_attr_t *attr"
+Destroy a thread attributes object.
+.It int Fn pthread_attr_getinheritsched "pthread_attr_t *attr" "int *inheritsched"
+Get the inherit scheduling attribute from a thread attributes object.
+.It int Fn pthread_attr_getschedparam "pthread_attr_t *attr" "struct sched_param *param"
+Get the scheduling parameter attribute from a thread attributes object.
+.It int Fn pthread_attr_getschedpolicy "pthread_attr_t *attr" "int *policy"
+Get the scheduling policy attribute from a thread attributes object.
+.It int Fn pthread_attr_getscope "pthread_attr_t *attr" "int *contentionscope"
+Get the contention scope attribute from a thread attributes object.
+.It int Fn pthread_attr_getstacksize "pthread_attr_t *attr" "size_t *stacksize"
+Get the stack size attribute from a thread attributes object.
+.It int Fn pthread_attr_getstackaddr "pthread_attr_t *attr" "void **stackaddr"
+Get the stack address attribute from a thread attributes object.
+.It int Fn pthread_attr_getdetachstate "pthread_attr_t *attr" "int *detachstate"
+Get the detach state attribute from a thread attributes object.
+.It int Fn pthread_attr_init "pthread_attr_t *attr"
+Initialize a thread attributes object with default values.
+.It int Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched"
+Set the inherit scheduling attribute in a thread attributes object.
+.It int Fn pthread_attr_setschedparam "pthread_attr_t *attr" "struct sched_param *param"
+Set the scheduling parameter attribute in a thread attributes object.
+.It int Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy"
+Set the scheduling policy attribute in a thread attributes object.
+.It int Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope"
+Set the contention scope attribute in a thread attributes object.
+.It int Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize"
+Set the stack size attribute in a thread attributes object.
+.It int Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr"
+Set the stack address attribute in a thread attributes object.
+.It int Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate"
+Set the detach state in a thread attributes object.
+.El
+.Sh MUTEX ROUTINES
+.Bl -tag -width Er
+.It int Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
+Destroy a mutex attributes object.
+.It int Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
+Initialize a mutex attributes object with default values.
+.It int Fn pthread_mutex_destroy "pthread_mutex_t *mutex"
+Destroy a mutex.
+.It int Fn pthread_mutex_init "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr"
+Initialise a mutex with specified attributes.
+.It int Fn pthread_mutex_lock "pthread_mutex_t *mutex"
+Lock a mutex and block until it becomes available.
+.It int Fn pthread_mutex_trylock "pthread_mutex_t *mutex"
+Try to lock a mutex, but don't block if the mutex is locked by another thread,
+including the current thread.
+.It int Fn pthread_mutex_unlock "pthread_mutex_t *mutex"
+Unlock a mutex.
+.El
+.Sh CONDITION VARIABLE ROUTINES
+.Bl -tag -width Er
+.It int Fn pthread_condattr_init "pthread_condattr_t *attr"
+Initialize a condition variable attributes object with default values.
+.It int Fn pthread_condattr_destroy "pthread_condattr_t *attr"
+Destroy a condition variable attributes object.
+.It int Fn pthread_cond_broadcast "pthread_cond_t *cond"
+Unblock all threads currently blocked on the specified condition variable.
+.It int Fn pthread_cond_destroy "pthread_cond_t *cond"
+Destroy a condition variable.
+.It int Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr"
+Initialize a condition variable with specified attributes.
+.It int Fn pthread_cond_signal "pthread_cond_t *cond"
+Unblock at least one of the threads blocked on the specified condition variable.
+.It int Fn pthread_cond_timedwait "pthread_cond_t *cond" "pthread_mutex_t *mutex" "const struct timespec *abstime"
+Wait no longer than the specified time for a condition and lock the specified mutex.
+.It int Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex"
+Wait for a condition and lock the specified mutex.
+.El
+.Sh PER-THREAD CONTEXT ROUTINES
+.Bl -tag -width Er
+.It int Fn pthread_key_create "pthread_key_t *key" "void (*routine)(void *)"
+Create a thread-specific data key.
+.It int Fn pthread_key_delete "pthread_key_t key"
+Delete a thread-specific data key.
+.It void * Fn pthread_getspecific "pthread_key_t key" "void **value_ptr"
+Get the thread-specific value for the specified key.
+.It int Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr"
+Set the thread-specific value for the specified key.
+.El
+.Sh CLEANUP ROUTINES
+.Bl -tag -width Er
+.It void Fn pthread_cleanup_pop "int execute"
+Remove the routine at the top of the calling thread's cancellation cleanup
+stack and optionally invoke it.
+.It void Fn pthread_cleanup_push "void (*routine)(void *)" "void *routine_arg"
+Push the specified cancellation cleanup handler onto the calling thread's 
+cancellation stack.
+.El
+.Sh INSTALLATION
+The current FreeBSD POSIX thread implementation is built in the library
+.Fa libc_r
+which contains both thread-safe libc functions and the thread functions.
+This library replaces
+.Fa libc
+for threaded applications.
+.Pp
+By default,
+.Fa libc_r
+is not built as part of a 'make world'. To build and install it, type:
+.Bl -item -offset indent
+.It
+cd /usr/src/lib/libc_r
+.It
+make depend && make all && make install
+.El
+.Pp
+This assumes you have a full source tree below /usr/src and that you have at
+least installed the header files in the way that 'make world' does.
+.Pp
+If you wish to install
+.Fa libc_r
+as part of 'make world', type:
+.Bl -item -offset indent
+.It
+cd /usr/src
+.It
+make -DWANT_LIBC_R world
+.El
+.Sh STANDARDS
+The functions in
+.Fa libc_r
+with the
+.Fa pthread_
+prefix and no
+.Fa _np
+suffix are expected to conform to IEEE
+.Pq Dq Tn POSIX
+Std 1003.1c when it is published.
+.Pp
+The functions in libc_r with the
+.Fa pthread_
+prefix and
+.Fa _np
+suffix are non-portable extensions to POSIX threads.