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.\" $FreeBSD$ 32.\" 33.Dd September 10, 1998 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. 44Multithreading is used to improve the performance of a 45program. 46.Pp 47The POSIX thread functions are summarized in this section in the following 48groups: 49.Bl -bullet -offset indent 50.It 51Thread Routines 52.It 53Attribute Object Routines 54.It 55Mutex Routines 56.It 57Condition Variable Routines 58.It 59Read/Write Lock Routines 60.It 61Per-Thread Context Routines 62.It 63Cleanup Routines 64.El 65.Sh THREAD ROUTINES 66.Bl -tag -width Er 67.It int Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg" 68Creates a new thread of execution. 69.It int Fn pthread_detach "pthread_t thread" 70Marks a thread for deletion. 71.It int Fn pthread_equal "pthread_t t1" "pthread_t t2" 72Compares two thread IDs. 73.It void Fn pthread_exit "void *value_ptr" 74Terminates the calling thread. 75.It int Fn pthread_join "pthread_t thread" "void **value_ptr" 76Causes the calling thread to wait for the termination of the specified thread. 77.It int Fn pthread_cancel "pthread_t thread" 78Cancels execution of a thread. 79.It int Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)" 80Calls an initialization routine once. 81.It pthread_t Fn pthread_self void 82Returns the thread ID of the calling thread. 83.El 84.Sh ATTRIBUTE OBJECT ROUTINES 85.Bl -tag -width Er 86.It int Fn pthread_attr_destroy "pthread_attr_t *attr" 87Destroy a thread attributes object. 88.It int Fn pthread_attr_getinheritsched "pthread_attr_t *attr" "int *inheritsched" 89Get the inherit scheduling attribute from a thread attributes object. 90.It int Fn pthread_attr_getschedparam "pthread_attr_t *attr" "struct sched_param *param" 91Get the scheduling parameter attribute from a thread attributes object. 92.It int Fn pthread_attr_getschedpolicy "pthread_attr_t *attr" "int *policy" 93Get the scheduling policy attribute from a thread attributes object. 94.It int Fn pthread_attr_getscope "pthread_attr_t *attr" "int *contentionscope" 95Get the contention scope attribute from a thread attributes object. 96.It int Fn pthread_attr_getstacksize "pthread_attr_t *attr" "size_t *stacksize" 97Get the stack size attribute from a thread attributes object. 98.It int Fn pthread_attr_getstackaddr "pthread_attr_t *attr" "void **stackaddr" 99Get the stack address attribute from a thread attributes object. 100.It int Fn pthread_attr_getdetachstate "pthread_attr_t *attr" "int *detachstate" 101Get the detach state attribute from a thread attributes object. 102.It int Fn pthread_attr_init "pthread_attr_t *attr" 103Initialize a thread attributes object with default values. 104.It int Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched" 105Set the inherit scheduling attribute in a thread attributes object. 106.It int Fn pthread_attr_setschedparam "pthread_attr_t *attr" "struct sched_param *param" 107Set the scheduling parameter attribute in a thread attributes object. 108.It int Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy" 109Set the scheduling policy attribute in a thread attributes object. 110.It int Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope" 111Set the contention scope attribute in a thread attributes object. 112.It int Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize" 113Set the stack size attribute in a thread attributes object. 114.It int Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr" 115Set the stack address attribute in a thread attributes object. 116.It int Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate" 117Set the detach state in a thread attributes object. 118.El 119.Sh MUTEX ROUTINES 120.Bl -tag -width Er 121.It int Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr" 122Destroy a mutex attributes object. 123.It int Fn pthread_mutexattr_init "pthread_mutexattr_t *attr" 124Initialize a mutex attributes object with default values. 125.It int Fn pthread_mutex_destroy "pthread_mutex_t *mutex" 126Destroy a mutex. 127.It int Fn pthread_mutex_init "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr" 128Initialize a mutex with specified attributes. 129.It int Fn pthread_mutex_lock "pthread_mutex_t *mutex" 130Lock a mutex and block until it becomes available. 131.It int Fn pthread_mutex_trylock "pthread_mutex_t *mutex" 132Try to lock a mutex, but don't block if the mutex is locked by another thread, 133including the current thread. 134.It int Fn pthread_mutex_unlock "pthread_mutex_t *mutex" 135Unlock a mutex. 136.El 137.Sh CONDITION VARIABLE ROUTINES 138.Bl -tag -width Er 139.It int Fn pthread_condattr_init "pthread_condattr_t *attr" 140Initialize a condition variable attributes object with default values. 141.It int Fn pthread_condattr_destroy "pthread_condattr_t *attr" 142Destroy a condition variable attributes object. 143.It int Fn pthread_cond_broadcast "pthread_cond_t *cond" 144Unblock all threads currently blocked on the specified condition variable. 145.It int Fn pthread_cond_destroy "pthread_cond_t *cond" 146Destroy a condition variable. 147.It int Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr" 148Initialize a condition variable with specified attributes. 149.It int Fn pthread_cond_signal "pthread_cond_t *cond" 150Unblock at least one of the threads blocked on the specified condition variable. 151.It int Fn pthread_cond_timedwait "pthread_cond_t *cond" "pthread_mutex_t *mutex" "const struct timespec *abstime" 152Wait no longer than the specified time for a condition and lock the specified mutex. 153.It int Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex" 154Wait for a condition and lock the specified mutex. 155.El 156.Sh READ/WRITE LOCK ROUTINES 157.Bl -tag -width Er 158.It int Fn pthread_rwlock_destroy "pthread_rwlock_t *lock" 159Destroy a read/write lock object. 160.It int Fn pthread_rwlock_init "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr" 161Initialize a read/write lock object. 162.It int Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock" 163Lock a read/write lock for reading, blocking until the lock can be 164acquired. 165.It int Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock" 166Attempt to lock a read/write lock for reading, without blocking if the 167lock is unavailable. 168.It int Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock" 169Attempt to lock a read/write lock for writing, without blocking if the 170lock is unavailable. 171.It int Fn pthread_rwlock_unlock "pthread_rwlock_t *lock" 172Unlock a read/write lock. 173.It int Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock" 174Lock a read/write lock for writing, blocking until the lock can be 175acquired. 176.It int Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr" 177Destroy a read/write lock attribute object. 178.It int Fn pthread_rwlockattr_getpshared "pthread_rwlockattr_t *attr" "int *pshared" 179Retrieve the process shared setting for the read/write lock attribute 180object. 181.It int Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr" 182Initialize a read/write lock attribute object. 183.It int Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int *pshared" 184Set the process shared setting for the read/write lock attribute object. 185.El 186.Sh PER-THREAD CONTEXT ROUTINES 187.Bl -tag -width Er 188.It int Fn pthread_key_create "pthread_key_t *key" "void (*routine)(void *)" 189Create a thread-specific data key. 190.It int Fn pthread_key_delete "pthread_key_t key" 191Delete a thread-specific data key. 192.It void * Fn pthread_getspecific "pthread_key_t key" "void **value_ptr" 193Get the thread-specific value for the specified key. 194.It int Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr" 195Set the thread-specific value for the specified key. 196.El 197.Sh CLEANUP ROUTINES 198.Bl -tag -width Er 199.It void Fn pthread_cleanup_pop "int execute" 200Remove the routine at the top of the calling thread's cancellation cleanup 201stack and optionally invoke it. 202.It void Fn pthread_cleanup_push "void (*routine)(void *)" "void *routine_arg" 203Push the specified cancellation cleanup handler onto the calling thread's 204cancellation stack. 205.El 206.Sh INSTALLATION 207The current FreeBSD POSIX thread implementation is built in the library 208.Fa libc_r 209which contains both thread-safe libc functions and the thread functions. 210This library replaces 211.Fa libc 212for threaded applications. 213.Pp 214By default, 215.Fa libc_r 216is built as part of a 'make world'. To disable the build of 217.Fa libc_r 218you must supply the '-DNOLIBC_R' option to 219.Xr make 1 . 220.Pp 221A FreeBSD specific option has been added to gcc to make linking 222threaded processes simple. 223.Fa gcc -pthread 224links a threaded process against 225.Fa libc_r 226instead of 227.Fa libc. 228.Sh SEE ALSO 229.Xr pthread_create 3 , 230.Xr pthread_detach 3 , 231.Xr pthread_equal 3 , 232.Xr pthread_exit 3 , 233.Xr pthread_join 3 , 234.Xr pthread_once 3 , 235.Xr pthread_self 3 , 236.Xr pthread_mutex_destroy 3 , 237.Xr pthread_mutex_init 3 , 238.Xr pthread_mutex_lock 3 , 239.Xr pthread_mutex_trylock 3 , 240.Xr pthread_mutex_unlock 3 , 241.Xr pthread_cond_broadcast 3 , 242.Xr pthread_cond_destroy 3 , 243.Xr pthread_cond_init 3 , 244.Xr pthread_cond_signal 3 , 245.Xr pthread_cond_timedwait 3 , 246.Xr pthread_cond_wait 3 , 247.Xr pthread_rwlock_destroy 3 , 248.Xr pthread_rwlock_init 3 , 249.Xr pthread_rwlock_rdlock 3 , 250.Xr pthread_rwlock_unlock 3 , 251.Xr pthread_rwlock_wrlock 3 , 252.Xr pthread_rwlockattr_destroy 3 , 253.Xr pthread_rwlockattr_getpshared 3 , 254.Xr pthread_rwlockattr_init 3 , 255.Xr pthread_rwlockattr_setpshared 3 , 256.Xr pthread_key_delete 3 , 257.Xr pthread_getspecific 3 , 258.Xr pthread_setspecific 3 , 259.Xr pthread_cleanup_pop 3 , 260.Xr pthread_cleanup_push 3 261.Sh STANDARDS 262The functions in 263.Fa libc_r 264with the 265.Fa pthread_ 266prefix and not 267.Fa _np 268suffix or 269.Fa pthread_rwlock 270prefix conform to IEEE 271.Pq Dq Tn POSIX 272Std 1003.1 Second Edition 1996-07-12 273.Pp 274The functions in libc_r with the 275.Fa pthread_ 276prefix and 277.Fa _np 278suffix are non-portable extensions to POSIX threads. 279.Pp 280The functions in libc_r with the 281.Fa pthread_rwlock 282prefix are extensions created by The Open Group as part of the Single 283UNIX Specification, Version 2. 284