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 36.Sh NAME 37.Nm pthread 38.Nd POSIX thread functions 39.Sh SYNOPSIS 40.In pthread.h 41.Sh DESCRIPTION 42POSIX threads are a set of functions that support applications with 43requirements for multiple flows of control, called 44.Fa threads , 45within a process. 46Multithreading is used to improve the performance of a 47program. 48.Pp 49The POSIX thread functions are summarized in this section in the following 50groups: 51.Bl -bullet -offset indent 52.It 53Thread Routines 54.It 55Attribute Object Routines 56.It 57Mutex Routines 58.It 59Condition Variable Routines 60.It 61Read/Write Lock Routines 62.It 63Per-Thread Context Routines 64.It 65Cleanup Routines 66.El 67.Sh THREAD ROUTINES 68.Bl -tag -width Er 69.It Xo 70.Ft int 71.Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg" 72.Xc 73Creates a new thread of execution. 74.It Xo 75.Ft int 76.Fn pthread_detach "pthread_t thread" 77.Xc 78Marks a thread for deletion. 79.It Xo 80.Ft int 81.Fn pthread_equal "pthread_t t1" "pthread_t t2" 82.Xc 83Compares two thread IDs. 84.It Xo 85.Ft void 86.Fn pthread_exit "void *value_ptr" 87.Xc 88Terminates the calling thread. 89.It Xo 90.Ft int 91.Fn pthread_join "pthread_t thread" "void **value_ptr" 92.Xc 93Causes the calling thread to wait for the termination of the specified thread. 94.It Xo 95.Ft int 96.Fn pthread_cancel "pthread_t thread" 97.Xc 98Cancels execution of a thread. 99.It Xo 100.Ft int 101.Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)" 102.Xc 103Calls an initialization routine once. 104.It Xo 105.Ft pthread_t 106.Fn pthread_self void 107.Xc 108Returns the thread ID of the calling thread. 109.El 110.Sh ATTRIBUTE OBJECT ROUTINES 111.Bl -tag -width Er 112.It Xo 113.Ft int 114.Fn pthread_attr_destroy "pthread_attr_t *attr" 115.Xc 116Destroy a thread attributes object. 117.It Xo 118.Ft int 119.Fn pthread_attr_getinheritsched "const pthread_attr_t *attr" "int *inheritsched" 120.Xc 121Get the inherit scheduling attribute from a thread attributes object. 122.It Xo 123.Ft int 124.Fn pthread_attr_getschedparam "const pthread_attr_t *attr" "struct sched_param *param" 125.Xc 126Get the scheduling parameter attribute from a thread attributes object. 127.It Xo 128.Ft int 129.Fn pthread_attr_getschedpolicy "const pthread_attr_t *attr" "int *policy" 130.Xc 131Get the scheduling policy attribute from a thread attributes object. 132.It Xo 133.Ft int 134.Fn pthread_attr_getscope "const pthread_attr_t *attr" "int *contentionscope" 135.Xc 136Get the contention scope attribute from a thread attributes object. 137.It Xo 138.Ft int 139.Fn pthread_attr_getstacksize "const pthread_attr_t *attr" "size_t *stacksize" 140.Xc 141Get the stack size attribute from a thread attributes object. 142.It Xo 143.Ft int 144.Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr" 145.Xc 146Get the stack address attribute from a thread attributes object. 147.It Xo 148.Ft int 149.Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate" 150.Xc 151Get the detach state attribute from a thread attributes object. 152.It Xo 153.Ft int 154.Fn pthread_attr_init "pthread_attr_t *attr" 155.Xc 156Initialize a thread attributes object with default values. 157.It Xo 158.Ft int 159.Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched" 160.Xc 161Set the inherit scheduling attribute in a thread attributes object. 162.It Xo 163.Ft int 164.Fn pthread_attr_setschedparam "pthread_attr_t *attr" "const struct sched_param *param" 165.Xc 166Set the scheduling parameter attribute in a thread attributes object. 167.It Xo 168.Ft int 169.Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy" 170.Xc 171Set the scheduling policy attribute in a thread attributes object. 172.It Xo 173.Ft int 174.Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope" 175.Xc 176Set the contention scope attribute in a thread attributes object. 177.It Xo 178.Ft int 179.Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize" 180.Xc 181Set the stack size attribute in a thread attributes object. 182.It Xo 183.Ft int 184.Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr" 185.Xc 186Set the stack address attribute in a thread attributes object. 187.It Xo 188.Ft int 189.Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate" 190.Xc 191Set the detach state in a thread attributes object. 192.El 193.Sh MUTEX ROUTINES 194.Bl -tag -width Er 195.It Xo 196.Ft int 197.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr" 198.Xc 199Destroy a mutex attributes object. 200.It Xo 201.Ft int 202.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr" 203.Xc 204Initialize a mutex attributes object with default values. 205.It Xo 206.Ft int 207.Fn pthread_mutex_destroy "pthread_mutex_t *mutex" 208.Xc 209Destroy a mutex. 210.It Xo 211.Ft int 212.Fn pthread_mutex_init "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr" 213.Xc 214Initialize a mutex with specified attributes. 215.It Xo 216.Ft int 217.Fn pthread_mutex_lock "pthread_mutex_t *mutex" 218.Xc 219Lock a mutex and block until it becomes available. 220.It Xo 221.Ft int 222.Fn pthread_mutex_trylock "pthread_mutex_t *mutex" 223.Xc 224Try to lock a mutex, but don't block if the mutex is locked by another thread, 225including the current thread. 226.It Xo 227.Ft int 228.Fn pthread_mutex_unlock "pthread_mutex_t *mutex" 229.Xc 230Unlock a mutex. 231.El 232.Sh CONDITION VARIABLE ROUTINES 233.Bl -tag -width Er 234.It Xo 235.Ft int 236.Fn pthread_condattr_init "pthread_condattr_t *attr" 237.Xc 238Initialize a condition variable attributes object with default values. 239.It Xo 240.Ft int 241.Fn pthread_condattr_destroy "pthread_condattr_t *attr" 242.Xc 243Destroy a condition variable attributes object. 244.It Xo 245.Ft int 246.Fn pthread_cond_broadcast "pthread_cond_t *cond" 247.Xc 248Unblock all threads currently blocked on the specified condition variable. 249.It Xo 250.Ft int 251.Fn pthread_cond_destroy "pthread_cond_t *cond" 252.Xc 253Destroy a condition variable. 254.It Xo 255.Ft int 256.Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr" 257.Xc 258Initialize a condition variable with specified attributes. 259.It Xo 260.Ft int 261.Fn pthread_cond_signal "pthread_cond_t *cond" 262.Xc 263Unblock at least one of the threads blocked on the specified condition variable. 264.It Xo 265.Ft int 266.Fn pthread_cond_timedwait "pthread_cond_t *cond" "pthread_mutex_t *mutex" "const struct timespec *abstime" 267.Xc 268Wait no longer than the specified time for a condition and lock the specified mutex. 269.It Xo 270.Ft int 271.Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex" 272.Xc 273Wait for a condition and lock the specified mutex. 274.El 275.Sh READ/WRITE LOCK ROUTINES 276.Bl -tag -width Er 277.It Xo 278.Ft int 279.Fn pthread_rwlock_destroy "pthread_rwlock_t *lock" 280.Xc 281Destroy a read/write lock object. 282.It Xo 283.Ft int 284.Fn pthread_rwlock_init "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr" 285.Xc 286Initialize a read/write lock object. 287.It Xo 288.Ft int 289.Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock" 290.Xc 291Lock a read/write lock for reading, blocking until the lock can be 292acquired. 293.It Xo 294.Ft int 295.Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock" 296.Xc 297Attempt to lock a read/write lock for reading, without blocking if the 298lock is unavailable. 299.It Xo 300.Ft int 301.Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock" 302.Xc 303Attempt to lock a read/write lock for writing, without blocking if the 304lock is unavailable. 305.It Xo 306.Ft int 307.Fn pthread_rwlock_unlock "pthread_rwlock_t *lock" 308.Xc 309Unlock a read/write lock. 310.It Xo 311.Ft int 312.Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock" 313.Xc 314Lock a read/write lock for writing, blocking until the lock can be 315acquired. 316.It Xo 317.Ft int 318.Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr" 319.Xc 320Destroy a read/write lock attribute object. 321.It Xo 322.Ft int 323.Fn pthread_rwlockattr_getpshared "const pthread_rwlockattr_t *attr" "int *pshared" 324.Xc 325Retrieve the process shared setting for the read/write lock attribute 326object. 327.It Xo 328.Ft int 329.Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr" 330.Xc 331Initialize a read/write lock attribute object. 332.It Xo 333.Ft int 334.Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared" 335.Xc 336Set the process shared setting for the read/write lock attribute object. 337.El 338.Sh PER-THREAD CONTEXT ROUTINES 339.Bl -tag -width Er 340.It Xo 341.Ft int 342.Fn pthread_key_create "pthread_key_t *key" "void (*routine)(void *)" 343.Xc 344Create a thread-specific data key. 345.It Xo 346.Ft int 347.Fn pthread_key_delete "pthread_key_t key" 348.Xc 349Delete a thread-specific data key. 350.It Xo 351.Ft "void *" 352.Fn pthread_getspecific "pthread_key_t key" 353.Xc 354Get the thread-specific value for the specified key. 355.It Xo 356.Ft int 357.Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr" 358.Xc 359Set the thread-specific value for the specified key. 360.El 361.Sh CLEANUP ROUTINES 362.Bl -tag -width Er 363.It Xo 364.Ft void 365.Fn pthread_cleanup_pop "int execute" 366.Xc 367Remove the routine at the top of the calling thread's cancellation cleanup 368stack and optionally invoke it. 369.It Xo 370.Ft void 371.Fn pthread_cleanup_push "void (*routine)(void *)" "void *routine_arg" 372.Xc 373Push the specified cancellation cleanup handler onto the calling thread's 374cancellation stack. 375.El 376.Sh INSTALLATION 377The current 378.Fx 379POSIX thread implementation is built in the library 380.Fa libc_r 381which contains both thread-safe libc functions and the thread functions. 382This library replaces 383.Fa libc 384for threaded applications. 385.Pp 386By default, 387.Fa libc_r 388is built as part of a 'make world'. To disable the build of 389.Fa libc_r 390you must supply the '-DNOLIBC_R' option to 391.Xr make 1 . 392.Pp 393A 394.Fx 395specific option has been added to gcc to make linking 396threaded processes simple. 397.Fa gcc -pthread 398links a threaded process against 399.Fa libc_r 400instead of 401.Fa libc . 402.Sh SEE ALSO 403.Xr pthread_cleanup_pop 3 , 404.Xr pthread_cleanup_push 3 , 405.Xr pthread_cond_broadcast 3 , 406.Xr pthread_cond_destroy 3 , 407.Xr pthread_cond_init 3 , 408.Xr pthread_cond_signal 3 , 409.Xr pthread_cond_timedwait 3 , 410.Xr pthread_cond_wait 3 , 411.Xr pthread_create 3 , 412.Xr pthread_detach 3 , 413.Xr pthread_equal 3 , 414.Xr pthread_exit 3 , 415.Xr pthread_getspecific 3 , 416.Xr pthread_join 3 , 417.Xr pthread_key_delete 3 , 418.Xr pthread_mutex_destroy 3 , 419.Xr pthread_mutex_init 3 , 420.Xr pthread_mutex_lock 3 , 421.Xr pthread_mutex_trylock 3 , 422.Xr pthread_mutex_unlock 3 , 423.Xr pthread_once 3 , 424.Xr pthread_rwlockattr_destroy 3 , 425.Xr pthread_rwlockattr_getpshared 3 , 426.Xr pthread_rwlockattr_init 3 , 427.Xr pthread_rwlockattr_setpshared 3 , 428.Xr pthread_rwlock_destroy 3 , 429.Xr pthread_rwlock_init 3 , 430.Xr pthread_rwlock_rdlock 3 , 431.Xr pthread_rwlock_unlock 3 , 432.Xr pthread_rwlock_wrlock 3 , 433.Xr pthread_self 3 , 434.Xr pthread_setspecific 3 435.Sh STANDARDS 436The functions in 437.Fa libc_r 438with the 439.Fa pthread_ 440prefix and not 441.Fa _np 442suffix or 443.Fa pthread_rwlock 444prefix conform to 445.St -p1003.1-96 . 446.Pp 447The functions in libc_r with the 448.Fa pthread_ 449prefix and 450.Fa _np 451suffix are non-portable extensions to POSIX threads. 452.Pp 453The functions in libc_r with the 454.Fa pthread_rwlock 455prefix are extensions created by The Open Group as part of the 456.St -susv2 . 457