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.Dd April 4, 1996 32.Dt PTHREAD 3 33.Os BSD 4 34.Sh NAME 35.Nm pthread 36.Nd POSIX thread functions 37.Sh DESCRIPTION 38POSIX threads are a set of functions that support applications with 39requirements for multiple flows of control, called 40.Fa threads , 41within a process. Multithreading is used to improve the performance of a 42program. 43.Pp 44The POSIX thread functions are summarized in this section in the following 45groups: 46.Bl -bullet -offset indent 47.It 48Thread routines 49.It 50Attribute Object Routines 51.It 52Mutex Routines 53.It 54Condition Variable Routines 55.It 56Per-Thread Context Routines 57.It 58Cleanup Routines 59.El 60.Sh THREAD ROUTINES 61.Bl -tag -width Er 62.It int Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg" 63Creates a new thread of execution. 64.It int Fn pthread_detach "pthread_t thread" 65Marks a thread for deletion. 66.It int Fn pthread_equal "pthread_t t1" "pthread_t t2" 67Compares two thread IDs. 68.It void Fn pthread_exit "void *value_ptr" 69Terminates the calling thread. 70.It int Fn pthread_join "pthread_t thread" "void **value_ptr" 71Causes the calling thread to wait for the termination of the specified thread. 72.It int Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)" 73Calls an initialization routine once. 74.It pthread_t Fn pthread_self void 75Returns the thread ID of the calling thread. 76.El 77.Sh ATTRIBUTE OBJECT ROUTINES 78.Bl -tag -width Er 79.It int Fn pthread_attr_destroy "pthread_attr_t *attr" 80Destroy a thread attributes object. 81.It int Fn pthread_attr_getinheritsched "pthread_attr_t *attr" "int *inheritsched" 82Get the inherit scheduling attribute from a thread attributes object. 83.It int Fn pthread_attr_getschedparam "pthread_attr_t *attr" "struct sched_param *param" 84Get the scheduling parameter attribute from a thread attributes object. 85.It int Fn pthread_attr_getschedpolicy "pthread_attr_t *attr" "int *policy" 86Get the scheduling policy attribute from a thread attributes object. 87.It int Fn pthread_attr_getscope "pthread_attr_t *attr" "int *contentionscope" 88Get the contention scope attribute from a thread attributes object. 89.It int Fn pthread_attr_getstacksize "pthread_attr_t *attr" "size_t *stacksize" 90Get the stack size attribute from a thread attributes object. 91.It int Fn pthread_attr_getstackaddr "pthread_attr_t *attr" "void **stackaddr" 92Get the stack address attribute from a thread attributes object. 93.It int Fn pthread_attr_getdetachstate "pthread_attr_t *attr" "int *detachstate" 94Get the detach state attribute from a thread attributes object. 95.It int Fn pthread_attr_init "pthread_attr_t *attr" 96Initialize a thread attributes object with default values. 97.It int Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched" 98Set the inherit scheduling attribute in a thread attributes object. 99.It int Fn pthread_attr_setschedparam "pthread_attr_t *attr" "struct sched_param *param" 100Set the scheduling parameter attribute in a thread attributes object. 101.It int Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy" 102Set the scheduling policy attribute in a thread attributes object. 103.It int Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope" 104Set the contention scope attribute in a thread attributes object. 105.It int Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize" 106Set the stack size attribute in a thread attributes object. 107.It int Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr" 108Set the stack address attribute in a thread attributes object. 109.It int Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate" 110Set the detach state in a thread attributes object. 111.El 112.Sh MUTEX ROUTINES 113.Bl -tag -width Er 114.It int Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr" 115Destroy a mutex attributes object. 116.It int Fn pthread_mutexattr_init "pthread_mutexattr_t *attr" 117Initialize a mutex attributes object with default values. 118.It int Fn pthread_mutex_destroy "pthread_mutex_t *mutex" 119Destroy a mutex. 120.It int Fn pthread_mutex_init "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr" 121Initialise a mutex with specified attributes. 122.It int Fn pthread_mutex_lock "pthread_mutex_t *mutex" 123Lock a mutex and block until it becomes available. 124.It int Fn pthread_mutex_trylock "pthread_mutex_t *mutex" 125Try to lock a mutex, but don't block if the mutex is locked by another thread, 126including the current thread. 127.It int Fn pthread_mutex_unlock "pthread_mutex_t *mutex" 128Unlock a mutex. 129.El 130.Sh CONDITION VARIABLE ROUTINES 131.Bl -tag -width Er 132.It int Fn pthread_condattr_init "pthread_condattr_t *attr" 133Initialize a condition variable attributes object with default values. 134.It int Fn pthread_condattr_destroy "pthread_condattr_t *attr" 135Destroy a condition variable attributes object. 136.It int Fn pthread_cond_broadcast "pthread_cond_t *cond" 137Unblock all threads currently blocked on the specified condition variable. 138.It int Fn pthread_cond_destroy "pthread_cond_t *cond" 139Destroy a condition variable. 140.It int Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr" 141Initialize a condition variable with specified attributes. 142.It int Fn pthread_cond_signal "pthread_cond_t *cond" 143Unblock at least one of the threads blocked on the specified condition variable. 144.It int Fn pthread_cond_timedwait "pthread_cond_t *cond" "pthread_mutex_t *mutex" "const struct timespec *abstime" 145Wait no longer than the specified time for a condition and lock the specified mutex. 146.It int Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex" 147Wait for a condition and lock the specified mutex. 148.El 149.Sh PER-THREAD CONTEXT ROUTINES 150.Bl -tag -width Er 151.It int Fn pthread_key_create "pthread_key_t *key" "void (*routine)(void *)" 152Create a thread-specific data key. 153.It int Fn pthread_key_delete "pthread_key_t key" 154Delete a thread-specific data key. 155.It void * Fn pthread_getspecific "pthread_key_t key" "void **value_ptr" 156Get the thread-specific value for the specified key. 157.It int Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr" 158Set the thread-specific value for the specified key. 159.El 160.Sh CLEANUP ROUTINES 161.Bl -tag -width Er 162.It void Fn pthread_cleanup_pop "int execute" 163Remove the routine at the top of the calling thread's cancellation cleanup 164stack and optionally invoke it. 165.It void Fn pthread_cleanup_push "void (*routine)(void *)" "void *routine_arg" 166Push the specified cancellation cleanup handler onto the calling thread's 167cancellation stack. 168.El 169.Sh INSTALLATION 170The current FreeBSD POSIX thread implementation is built in the library 171.Fa libc_r 172which contains both thread-safe libc functions and the thread functions. 173This library replaces 174.Fa libc 175for threaded applications. 176.Pp 177By default, 178.Fa libc_r 179is not built as part of a 'make world'. To build and install it, type: 180.Bl -item -offset indent 181.It 182cd /usr/src/lib/libc_r 183.It 184make depend && make all && make install 185.El 186.Pp 187This assumes you have a full source tree below /usr/src and that you have at 188least installed the header files in the way that 'make world' does. 189.Pp 190If you wish to install 191.Fa libc_r 192as part of 'make world', type: 193.Bl -item -offset indent 194.It 195cd /usr/src 196.It 197make -DWANT_LIBC_R world 198.El 199.Sh STANDARDS 200The functions in 201.Fa libc_r 202with the 203.Fa pthread_ 204prefix and no 205.Fa _np 206suffix are expected to conform to IEEE 207.Pq Dq Tn POSIX 208Std 1003.1c when it is published. 209.Pp 210The functions in libc_r with the 211.Fa pthread_ 212prefix and 213.Fa _np 214suffix are non-portable extensions to POSIX threads. 215