From 7350d1d3b2ec940c89a2b20f9d09985d9fd9e9d7 Mon Sep 17 00:00:00 2001 From: julian Date: Tue, 20 Aug 1996 08:22:01 +0000 Subject: Submitted by: John Birrell 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. --- share/man/man3/Makefile | 6 +- share/man/man3/pthread.3 | 214 +++++++++++++++++++++++++++++++++++ share/man/man3/pthread_create.3 | 109 ++++++++++++++++++ share/man/man3/pthread_detach.3 | 79 +++++++++++++ share/man/man3/pthread_equal.3 | 66 +++++++++++ share/man/man3/pthread_exit.3 | 99 ++++++++++++++++ share/man/man3/pthread_getspecific.3 | 80 +++++++++++++ share/man/man3/pthread_join.3 | 100 ++++++++++++++++ share/man/man3/pthread_key_create.3 | 98 ++++++++++++++++ share/man/man3/pthread_key_delete.3 | 92 +++++++++++++++ share/man/man3/pthread_once.3 | 100 ++++++++++++++++ share/man/man3/pthread_self.3 | 59 ++++++++++ share/man/man3/pthread_setspecific.3 | 91 +++++++++++++++ 13 files changed, 1190 insertions(+), 3 deletions(-) create mode 100644 share/man/man3/pthread.3 create mode 100644 share/man/man3/pthread_create.3 create mode 100644 share/man/man3/pthread_detach.3 create mode 100644 share/man/man3/pthread_equal.3 create mode 100644 share/man/man3/pthread_exit.3 create mode 100644 share/man/man3/pthread_getspecific.3 create mode 100644 share/man/man3/pthread_join.3 create mode 100644 share/man/man3/pthread_key_create.3 create mode 100644 share/man/man3/pthread_key_delete.3 create mode 100644 share/man/man3/pthread_once.3 create mode 100644 share/man/man3/pthread_self.3 create mode 100644 share/man/man3/pthread_setspecific.3 (limited to 'share/man') diff --git a/share/man/man3/Makefile b/share/man/man3/Makefile index 1462810..6fef09f 100644 --- a/share/man/man3/Makefile +++ b/share/man/man3/Makefile @@ -1,8 +1,8 @@ # @(#)Makefile 8.2 (Berkeley) 12/13/93 -# $Id: $ +# $Id: Makefile,v 1.9 1996/05/29 00:58:47 wosch Exp $ -MAN3= assert.3 bitstring.3 end.3 fpgetround.3 intro.3 queue.3 stdarg.3 \ - sysexits.3 +MAN3= assert.3 bitstring.3 end.3 fpgetround.3 intro.3 pthread.3 queue.3 \ + stdarg.3 sysexits.3 MLINKS+=bitstring.3 bit_alloc.3 bitstring.3 bit_clear.3 \ bitstring.3 bit_decl.3 bitstring.3 bit_ffs.3 bitstring.3 bit_nclear.3 \ bitstring.3 bit_nset.3 bitstring.3 bit_set.3 \ 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 . +.\" 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. diff --git a/share/man/man3/pthread_create.3 b/share/man/man3/pthread_create.3 new file mode 100644 index 0000000..5ac24e8 --- /dev/null +++ b/share/man/man3/pthread_create.3 @@ -0,0 +1,109 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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_CREATE 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_create +.Nd create a new thread +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg" +.Sh DESCRIPTION +The +.Fn pthread_create +function is used to create a new thread, with attributes specified by +.Fa attr , +within a process. If +.Fa attr +is NULL, the default attributes are used. If the attributes specified by +.Fa attr +are modified later, the thread's attributes are not affected. Upon +successful completion +.Fn pthread_create +will store the ID of the created thread in the location specified by +.Fa thread . +.Pp +The thread is created executing +.Fa start_routine +with +.Fa arg +as its sole argument. If the +.Fa start_routine +returns, the effect is as if there was an implicit call to +.Fn pthread_exit +using the return value of +.Fa start_toutine +as the exit status. Note that the thread in which +.Fn main +was originally invoked differs from this. When it returns from +.Fn main , +the effect is as if there was an implicit call to +.Fn exit using the return value of +.Fn main +as the exit status. +.Pp +The signal state of the new thread is initialized as: +.Bl -bullet -offset indent +.It +The signal mask is inherited from the creating thread. +.It +The set of signals pending for the new thread is empty. +.El +.Sh RETURN VALUES +If successful, the +.Fn pthread_create +function will return zero. Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +.Fn pthread_create +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacked the necessary resources to create another thread, or +the system-imposed limit on the total number of threads in a process +[PTHREAD_THREADS_MAX] would be exceeded. +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Pp +.Sh SEE ALSO +.Xr pthread_exit 3 , +.Xr pthread_join 3 , +.Xr fork 2 +.Sh STANDARDS +.Fn pthread_create +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/share/man/man3/pthread_detach.3 b/share/man/man3/pthread_detach.3 new file mode 100644 index 0000000..d2a60dd --- /dev/null +++ b/share/man/man3/pthread_detach.3 @@ -0,0 +1,79 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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_DETACH 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_detach +.Nd detach a thread +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn pthread_detach "pthread_t thread" +.Sh DESCRIPTION +The +.Fn pthread_detach +function is used to indicate to the implementation that storage for the +thread +.Fa thread +can be reclaimed when the thread terminates. If +.Fa thread +has not terminated, +.Fn pthread_detach +will not cause it to terminate. The effect of multiple +.Fn pthread_detach +calls on the same target thread is unspecified. +.Sh RETURN VALUES +If successful, the +.Fn pthread_detach +function will return zero. Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +.Fn pthread_detach +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The implementation has detected that the value specified by +.Fa thread +does not refer to a joinable thread. +.It Bq Er ESRCH +No thread could be found corresponding to that specified by the given +thread ID, +.Fa thread . +.El +.Pp +.Sh SEE ALSO +.Xr pthread_join 3 +.Sh STANDARDS +.Fn pthread_detach +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/share/man/man3/pthread_equal.3 b/share/man/man3/pthread_equal.3 new file mode 100644 index 0000000..3324855 --- /dev/null +++ b/share/man/man3/pthread_equal.3 @@ -0,0 +1,66 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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_EQUAL 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_equal +.Nd compare thread IDs +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn pthread_equal "pthread_t t1" "pthread_t t2" +.Sh DESCRIPTION +The +.Fn pthread_equal +function compares the thread IDs +.Fa t1 +and +.Fa t2 . +.Sh RETURN VALUES +The +.Fn pthread_equal +function will non-zero if the thread IDs +.Fa t1 +and +.Fa t2 +correspond to the same thread, otherwise it will return zero. +.Sh ERRORS +None. +.Pp +.Sh SEE ALSO +.Xr pthread_create 3 , +.Xr pthread_exit 3 +.Sh STANDARDS +.Fn pthread_equal +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/share/man/man3/pthread_exit.3 b/share/man/man3/pthread_exit.3 new file mode 100644 index 0000000..2b0799e --- /dev/null +++ b/share/man/man3/pthread_exit.3 @@ -0,0 +1,99 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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_EXIT 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_exit +.Nd terminate the calling thread +.Sh SYNOPSIS +.Fd #include +.Ft void +.Fn pthread_exit "void *value_ptr" +.Sh DESCRIPTION +The +.Fn pthread_exit +function terminates the calling thread and makes the value +.Fa value_ptr +available to any successful join with the terminating thread. Any +cancellation cleanup handlers that have been pushed and are not yet popped +are popped in the reverse order that they were pushed and then executed. +After all cancellation handlers have been executed, if the thread has any +thread-specific data, appropriate destructor functions are called in an +unspecified order. Thread termination does not release any application +visible process resources, including, but not limited to, mutexes and +file descriptors, nor does it perform any process level cleanup +actions, including, but not limited to, calling +.Fn atexit +routines that may exist. +.Pp +An implicit call to +.Fn pthread_exit +is made when a thread other than the thread in which +.Fn main +was first invoked returns from the start routine that was used to create +it. The function's return value serves as the thread's exit status. +.Pp +The behavior of +.Fn pthread_exit +is undefied if called from a cancellation handler or destructor function +that was invoked as the result of an implicit or explicit call to +.Fn pthread_exit . +.Pp +After a thread has terminated, the result of access to local (auto) +variables of the thread is undefined. Thus, references to local variables +of the exiting thread should not be used for the +.Fn pthread_exit +.Fa value_ptr +parameter value. +.Pp +The process will exit with an exit status of 0 after the last thread has +been terminated. The behavior is as if the implementation called +.Fn exit +with a zero argument at thread termination time. +.Pp +.Sh RETURN VALUES +The +.Fn pthread_exit +function cannot return to its caller. +.Sh ERRORS +None. +.Pp +.Sh SEE ALSO +.Xr pthread_create 3 , +.Xr pthread_join 3 , +.Xr exit 2, +.Xr _exit 2 +.Sh STANDARDS +.Fn pthread_exit +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/share/man/man3/pthread_getspecific.3 b/share/man/man3/pthread_getspecific.3 new file mode 100644 index 0000000..7df4de0 --- /dev/null +++ b/share/man/man3/pthread_getspecific.3 @@ -0,0 +1,80 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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_GETSPECIFIC 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_getspecific +.Nd get a thread-specific data value +.Sh SYNOPSIS +.Fd #include +.Ft void * +.Fn pthread_getspecific "pthread_key_t key" +.Sh DESCRIPTION +The +.Fn pthread_getspecific +function returns the value currently bound to the specified +.Fa key +on behalf of the calling thread. +.Pp +The effect of calling +.Fn pthread_getspecific +with a +.Fa key +value not obtained from +.Fn pthread_key_create +or after +.Fa key +has been deleted with +.Fn pthread_key_delete +is undefined. +.Pp +.Fn pthread_getspecific +may be called from a thread-specific data destructor function. +.Sh RETURN VALUES +The +.Fn pthread_getspecific +function will return the thread-specific data value associated with the given +.Fa key . +If no thread-specific data value is associated with +.Fa key , +then the value NULL is returned. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr pthread_key_create 3 , +.Xr pthread_key_delete 3 +.Xr pthread_setspecific 3 +.Sh STANDARDS +.Fn pthread_getspecific +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/share/man/man3/pthread_join.3 b/share/man/man3/pthread_join.3 new file mode 100644 index 0000000..374b832 --- /dev/null +++ b/share/man/man3/pthread_join.3 @@ -0,0 +1,100 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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_JOIN 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_join +.Nd wait for thread termination +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn pthread_join "pthread_t thread" "void **value_ptr" +.Sh DESCRIPTION +The +.Fn pthread_join +function suspends execution of the calling thread until the target +.Fa thread +terminates unless the target +.Fa thread +has already terminated. +.Pp +On return from a successful +.Fn pthread_join +call with a non-NULL +.Fa value_ptr +argument, the value passed to +.Fn pthread_exit +by the terminating thread is stored in the location referenced by +.Fa value_ptr . +When a +.Fn pthread_join +returns successfully, the target thread has been terminated. The results +of multiple simultaneous calls to +.Fn pthread_join +specifying the same target thread are undefined. If the thread calling +.Fn pthread_join +is cancelled, then the target thread is not detached. +.Pp +A thread that has exited but remains unjoined counts against +[_POSIX_THREAD_THREADS_MAX]. +.Pp +.Sh RETURN VALUES +If successful, the +.Fn pthread_join +function will return zero. Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +.Fn pthread_join +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The implementation has detected that the value specified by +.Fa thread +does not refer to a joinable thread. +.It Bq Er ESRCH +No thread could be found corresponding to that specified by the given +thread ID, +.Fa thread . +.It Bq Er EDEADLK +A deadlock was detected or the value of +.Fa thread +specifies the calling thread. +.El +.Pp +.Sh SEE ALSO +.Xr pthread_create 3 , +.Xr wait 2 +.Sh STANDARDS +.Fn pthread_join +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/share/man/man3/pthread_key_create.3 b/share/man/man3/pthread_key_create.3 new file mode 100644 index 0000000..1bcf9e0 --- /dev/null +++ b/share/man/man3/pthread_key_create.3 @@ -0,0 +1,98 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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_KEY_CREATE 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_key_create +.Nd thread-specific data key creation +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn pthread_key_create "pthread_key_t *key" "void (*destructor)(void *)" +.Sh DESCRIPTION +The +.Fn pthread_key_create +function creates a thread-specific data key visible to all threads in the +process. Key values provided by +.Fn pthread_key_create +are opaque objects used to locate thread-specific data. Although the same +key value may be used by different threads, the values bound to the key +by +.Fn pthread_setspecific +are maintained on a per-thread basis and persist for the life of the calling +thread. +.Pp +Upon key creation, the value NULL is associated with the new key in all +active threads. Upon thread creation, the value NULL is associated with all +defined keys in the new thread. +.Pp +An optional destructor function may be associated with each key value. At +thread exit, if a key value has a non-NULL destructor pointer, and the +thread has a non-NULL value associated with the key, the function pointed +to is called with the current associated value as its sole argument. The +order of destructor calls is unspecified if more than one destructor exists +for a thread when it exits. +.Pp +If, after all the destructors have been called for all non-NULL values +with associated destructors, there are still some non-NULL values with +associated destructors, then the process is repeated. If, after at least +[PTHREAD_DESTRUCTOR_ITERATIONS] iterations of destructor calls for +outstanding non-NULL values, there are still some non-NULL values with +associated destructors, the implementation stops calling destructors. +.Sh RETURN VALUES +If successful, the +.Fn pthread_key_create +function will store the newly created key value at the location specified by +.Fa key +and returns zero. Otherwise an error number will be returned to indicate +the error. +.Sh ERRORS +.Fn pthread_key_create +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacked the necessary resources to create another thread-specific +data key, or the system-imposed limit on the total number of keys per process +[PTHREAD_KEYS_MAX] would be exceeded. +.It Bq Er ENOMEM +Insufficient memory exists to create the key. +.El +.Pp +.Sh SEE ALSO +.Xr pthread_getspecific 3 , +.Xr pthread_setspecific 3 , +.Xr pthread_key_delete 3 +.Sh STANDARDS +.Fn pthread_key_create +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/share/man/man3/pthread_key_delete.3 b/share/man/man3/pthread_key_delete.3 new file mode 100644 index 0000000..732c562 --- /dev/null +++ b/share/man/man3/pthread_key_delete.3 @@ -0,0 +1,92 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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_KEY_DELETE 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_key_delete +.Nd delete a thread-specific data key +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn pthread_key_delete "pthread_key_t key" +.Sh DESCRIPTION +The +.Fn pthread_key_delete +function deletes a thread-specific data key previously returned by +.Fn pthread_key_create . +The thread-specific data values associated with +.Fa key +need not be NULL at the time that +.Fn pthread_key_delete +is called. It is the responsibility of the application to free any +application storage or perform any cleanup actions for data structures +related to the deleted key or associated thread-specific data in any threads; +this cleanup can be done either before or after +.Fn pthread_key_delete +is called. Any attempt to use +.Fa key +following the call to +.Fn pthread_key_delete +results in undefined behavior. +.Pp +The +.Fn pthread_key_delete +function is callable from within destructor functions. Destructor functions +are not invoked by +.Fn pthread_key_delete . +Any destructor function that may have been associated with +.Fa key +will no longer be called upon thread exit. +.Sh RETURN VALUES +If successful, the +.Fn pthread_key_delete +function will return zero. Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +.Fn pthread_key_delete +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa key +value is invalid. +.El +.Pp +.Sh SEE ALSO +.Xr pthread_key_create 3 , +.Xr pthread_getspecific 3 , +.Xr pthread_setspecific 3 +.Sh STANDARDS +.Fn pthread_key_delete +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/share/man/man3/pthread_once.3 b/share/man/man3/pthread_once.3 new file mode 100644 index 0000000..9ade42f --- /dev/null +++ b/share/man/man3/pthread_once.3 @@ -0,0 +1,100 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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_ONCE 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_once +.Nd dynamic package initialization +.Sh SYNOPSIS +.Fd #include +.Pp +pthread_once +.Fa once_control += PTHREAD_ONCE_INIT; +.Ft int +.Fn pthread_once "pthread_once_t *once_control" "void *(*init_routine)(void)" +.Sh DESCRIPTION +The first call to +.Fn pthread_once +by any thread in a process, with a given +.Fa once_control , +will call the +.Fn init_routine +with no arguments. Subsequent calls to +.Fn pthread_once +with the same +.Fa once_control +will not call the +.Fn init_routine . +On return from +.Fn pthread_once , +it is guaranteed that +.Fn init_routine +has completed. The +.Fa once_control +parameter is used to determine whether the associated initialization +routine has been called. +.Pp +The function +.Fn pthread_once +is not a cancellation point. However, if +.Fn init_routine +is a cancellation point and is cancelled, the effect on +.Fa once_control is as if +.Fn pthread_once +was never called. +.Pp +The constant +.Fa PTHREAD_ONCE_INIT +is defined by header +.Aq Pa pthread.h . +.Pp +The behavior of +.Fn pthread_once +is undefined if +.Fa once_control +has automatic storage duration or is not initialized by +.Fa PTHREAD_ONCE_INIT . +.Pp +.Sh RETURN VALUES +If successful, the +.Fn pthread_once +function will return zero. Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +None. +.Pp +.Sh STANDARDS +.Fn pthread_once +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/share/man/man3/pthread_self.3 b/share/man/man3/pthread_self.3 new file mode 100644 index 0000000..9ba0ee6 --- /dev/null +++ b/share/man/man3/pthread_self.3 @@ -0,0 +1,59 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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_SELF 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_self +.Nd get the calling thread's ID +.Sh SYNOPSIS +.Fd #include +.Ft pthread_t +.Fn pthread_self "void" +.Sh DESCRIPTION +The +.Fn pthread_self +function returns the thread ID of the calling thread. +.Sh RETURN VALUES +The +.Fn pthread_self +function returns the thread ID of the calling thread. +.Sh ERRORS +None. +.Pp +.Sh SEE ALSO +.Xr pthread_create 3 , +.Xr pthread_equal 3 +.Sh STANDARDS +.Fn pthread_self +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. diff --git a/share/man/man3/pthread_setspecific.3 b/share/man/man3/pthread_setspecific.3 new file mode 100644 index 0000000..05b947f --- /dev/null +++ b/share/man/man3/pthread_setspecific.3 @@ -0,0 +1,91 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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_SETSPECIFIC 3 +.Os BSD 4 +.Sh NAME +.Nm pthread_setspecific +.Nd set a thread-specific data value +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn pthread_setspecific "pthread_key_t key" "const void *value" +.Sh DESCRIPTION +The +.Fn pthread_setspecific +function associates a thread-specific value with a +.Fa key +obtained via a previous call to +.Fn pthread_key_create . +Different threads man bind different values to the same key. These values are +typically pointers to blocks of dynamically allocated memory that have been +reserved for use by the calling thread. +.Pp +The effect of calling +.Fn pthread_setspecific +with a key value not obtained from +.Fn pthread_key_create +or after +.Fa key +has been deleted with +.Fn pthread_key_delete +is undefined. +.Pp +.Fn pthread_setspecific +may be called from a thread-specific data destructor function, however this +may result in lost storage or infinite loops. +.Sh RETURN VALUES +If successful, the +.Fn pthread_setspecific +function will return zero. Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +.Fn pthread_setspecific +will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory exists to associate the value with the +.Fa key . +.It Bq Er EINVAL +The +.Fa key +value is invalid. +.El +.Pp +.Sh SEE ALSO +.Xr pthread_key_create 3 , +.Xr pthread_key_delete 3 , +.Xr pthread_getspecific 3 +.Sh STANDARDS +.Fn pthread_setspecific +is expected to conform to IEEE +.Pq Dq Tn POSIX +Std 1003.1c when it is published. -- cgit v1.1