1.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by John Birrell. 15.\" 4. Neither the name of the author nor the names of any co-contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" $Id$ 32.\" 33.Dd April 4, 1996 34.Dt PTHREAD 3 35.Os BSD 4 36.Sh NAME 37.Nm pthread 38.Nd POSIX thread functions 39.Sh DESCRIPTION 40POSIX threads are a set of functions that support applications with 41requirements for multiple flows of control, called 42.Fa threads , 43within a process. Multithreading is used to improve the performance of a 44program. 45.Pp 46The POSIX thread functions are summarized in this section in the following 47groups: 48.Bl -bullet -offset indent 49.It 50Thread routines 51.It 52Attribute Object Routines 53.It 54Mutex Routines 55.It 56Condition Variable Routines 57.It 58Per-Thread Context Routines 59.It 60Cleanup Routines 61.El 62.Sh THREAD ROUTINES 63.Bl -tag -width Er 64.It int Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg" 65Creates a new thread of execution. 66.It int Fn pthread_detach "pthread_t thread" 67Marks a thread for deletion. 68.It int Fn pthread_equal "pthread_t t1" "pthread_t t2" 69Compares two thread IDs. 70.It void Fn pthread_exit "void *value_ptr" 71Terminates the calling thread. 72.It int Fn pthread_join "pthread_t thread" "void **value_ptr" 73Causes the calling thread to wait for the termination of the specified thread. 74.It int Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)" 75Calls an initialization routine once. 76.It pthread_t Fn pthread_self void 77Returns the thread ID of the calling thread. 78.El 79.Sh ATTRIBUTE OBJECT ROUTINES 80.Bl -tag -width Er 81.It int Fn pthread_attr_destroy "pthread_attr_t *attr" 82Destroy a thread attributes object. 83.It int Fn pthread_attr_getinheritsched "pthread_attr_t *attr" "int *inheritsched" 84Get the inherit scheduling attribute from a thread attributes object. 85.It int Fn pthread_attr_getschedparam "pthread_attr_t *attr" "struct sched_param *param" 86Get the scheduling parameter attribute from a thread attributes object. 87.It int Fn pthread_attr_getschedpolicy "pthread_attr_t *attr" "int *policy" 88Get the scheduling policy attribute from a thread attributes object. 89.It int Fn pthread_attr_getscope "pthread_attr_t *attr" "int *contentionscope" 90Get the contention scope attribute from a thread attributes object. 91.It int Fn pthread_attr_getstacksize "pthread_attr_t *attr" "size_t *stacksize" 92Get the stack size attribute from a thread attributes object. 93.It int Fn pthread_attr_getstackaddr "pthread_attr_t *attr" "void **stackaddr" 94Get the stack address attribute from a thread attributes object. 95.It int Fn pthread_attr_getdetachstate "pthread_attr_t *attr" "int *detachstate" 96Get the detach state attribute from a thread attributes object. 97.It int Fn pthread_attr_init "pthread_attr_t *attr" 98Initialize a thread attributes object with default values. 99.It int Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched" 100Set the inherit scheduling attribute in a thread attributes object. 101.It int Fn pthread_attr_setschedparam "pthread_attr_t *attr" "struct sched_param *param" 102Set the scheduling parameter attribute in a thread attributes object. 103.It int Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy" 104Set the scheduling policy attribute in a thread attributes object. 105.It int Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope" 106Set the contention scope attribute in a thread attributes object. 107.It int Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize" 108Set the stack size attribute in a thread attributes object. 109.It int Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr" 110Set the stack address attribute in a thread attributes object. 111.It int Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate" 112Set the detach state in a thread attributes object. 113.El 114.Sh MUTEX ROUTINES 115.Bl -tag -width Er 116.It int Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr" 117Destroy a mutex attributes object. 118.It int Fn pthread_mutexattr_init "pthread_mutexattr_t *attr" 119Initialize a mutex attributes object with default values. 120.It int Fn pthread_mutex_destroy "pthread_mutex_t *mutex" 121Destroy a mutex. 122.It int Fn pthread_mutex_init "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr" 123Initialise a mutex with specified attributes. 124.It int Fn pthread_mutex_lock "pthread_mutex_t *mutex" 125Lock a mutex and block until it becomes available. 126.It int Fn pthread_mutex_trylock "pthread_mutex_t *mutex" 127Try to lock a mutex, but don't block if the mutex is locked by another thread, 128including the current thread. 129.It int Fn pthread_mutex_unlock "pthread_mutex_t *mutex" 130Unlock a mutex. 131.El 132.Sh CONDITION VARIABLE ROUTINES 133.Bl -tag -width Er 134.It int Fn pthread_condattr_init "pthread_condattr_t *attr" 135Initialize a condition variable attributes object with default values. 136.It int Fn pthread_condattr_destroy "pthread_condattr_t *attr" 137Destroy a condition variable attributes object. 138.It int Fn pthread_cond_broadcast "pthread_cond_t *cond" 139Unblock all threads currently blocked on the specified condition variable. 140.It int Fn pthread_cond_destroy "pthread_cond_t *cond" 141Destroy a condition variable. 142.It int Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr" 143Initialize a condition variable with specified attributes. 144.It int Fn pthread_cond_signal "pthread_cond_t *cond" 145Unblock at least one of the threads blocked on the specified condition variable. 146.It int Fn pthread_cond_timedwait "pthread_cond_t *cond" "pthread_mutex_t *mutex" "const struct timespec *abstime" 147Wait no longer than the specified time for a condition and lock the specified mutex. 148.It int Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex" 149Wait for a condition and lock the specified mutex. 150.El 151.Sh PER-THREAD CONTEXT ROUTINES 152.Bl -tag -width Er 153.It int Fn pthread_key_create "pthread_key_t *key" "void (*routine)(void *)" 154Create a thread-specific data key. 155.It int Fn pthread_key_delete "pthread_key_t key" 156Delete a thread-specific data key. 157.It void * Fn pthread_getspecific "pthread_key_t key" "void **value_ptr" 158Get the thread-specific value for the specified key. 159.It int Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr" 160Set the thread-specific value for the specified key. 161.El 162.Sh CLEANUP ROUTINES 163.Bl -tag -width Er 164.It void Fn pthread_cleanup_pop "int execute" 165Remove the routine at the top of the calling thread's cancellation cleanup 166stack and optionally invoke it. 167.It void Fn pthread_cleanup_push "void (*routine)(void *)" "void *routine_arg" 168Push the specified cancellation cleanup handler onto the calling thread's 169cancellation stack. 170.El 171.Sh INSTALLATION 172The current FreeBSD POSIX thread implementation is built in the library 173.Fa libc_r 174which contains both thread-safe libc functions and the thread functions. 175This library replaces 176.Fa libc 177for threaded applications. 178.Pp 179By default, 180.Fa libc_r 181is not built as part of a 'make world'. To build and install it, type: 182.Bl -item -offset indent 183.It 184cd /usr/src/lib/libc_r 185.It 186make depend && make all && make install 187.El 188.Pp 189This assumes you have a full source tree below /usr/src and that you have at 190least installed the header files in the way that 'make world' does. 191.Pp 192If you wish to install 193.Fa libc_r 194as part of 'make world', type: 195.Bl -item -offset indent 196.It 197cd /usr/src 198.It 199make -DWANT_LIBC_R world 200.El 201.Sh STANDARDS 202The functions in 203.Fa libc_r 204with the 205.Fa pthread_ 206prefix and no 207.Fa _np 208suffix are expected to conform to IEEE 209.Pq Dq Tn POSIX 210Std 1003.1c when it is published. 211.Pp 212The functions in libc_r with the 213.Fa pthread_ 214prefix and 215.Fa _np 216suffix are non-portable extensions to POSIX threads. 217