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: src/share/man/man3/pthread.3,v 1.33 2009/04/01 08:08:25 trhodes Exp $ 32.\" $DragonFly: src/share/man/man3/pthread.3,v 1.5 2007/09/14 19:47:03 swildner Exp $ 33.\" 34.Dd July 10, 2009 35.Dt PTHREAD 3 36.Os 37.Sh NAME 38.Nm pthread 39.Nd POSIX thread functions 40.Sh LIBRARY 41.Lb libpthread 42.Sh SYNOPSIS 43.In pthread.h 44.Sh DESCRIPTION 45POSIX threads are a set of functions that support applications with 46requirements for multiple flows of control, called 47.Em threads , 48within a process. 49Multithreading is used to improve the performance of a 50program. 51.Pp 52The POSIX thread functions are summarized in this section in the following 53groups: 54.Pp 55.Bl -bullet -offset indent -compact 56.It 57Thread Routines 58.It 59Attribute Object Routines 60.It 61Mutex Routines 62.It 63Condition Variable Routines 64.It 65Read/Write Lock Routines 66.It 67Per-Thread Context Routines 68.It 69Cleanup Routines 70.El 71.Ss Thread Routines 72.Bl -tag -width indent 73.It Xo 74.Ft int 75.Fo pthread_create 76.Fa "pthread_t *thread" "const pthread_attr_t *attr" 77.Fa "void *\*[lp]*start_routine\*[rp]\*[lp]void *\*[rp]" "void *arg" 78.Fc 79.Xc 80Creates a new thread of execution. 81.It Xo 82.Ft int 83.Fn pthread_cancel "pthread_t thread" 84.Xc 85Cancels execution of a thread. 86.It Xo 87.Ft int 88.Fn pthread_detach "pthread_t thread" 89.Xc 90Marks a thread for deletion. 91.It Xo 92.Ft int 93.Fn pthread_equal "pthread_t t1" "pthread_t t2" 94.Xc 95Compares two thread IDs. 96.It Xo 97.Ft void 98.Fn pthread_exit "void *value_ptr" 99.Xc 100Terminates the calling thread. 101.It Xo 102.Ft int 103.Fn pthread_join "pthread_t thread" "void **value_ptr" 104.Xc 105Causes the calling thread to wait for the termination of the specified thread. 106.It Xo 107.Ft int 108.Fn pthread_kill "pthread_t thread" "int sig" 109.Xc 110Delivers a signal to a specified thread. 111.It Xo 112.Ft int 113.Fn pthread_once "pthread_once_t *once_control" "void \*[lp]*init_routine\*[rp]\*[lp]void\*[rp]" 114.Xc 115Calls an initialization routine once. 116.It Xo 117.Ft pthread_t 118.Fn pthread_self void 119.Xc 120Returns the thread ID of the calling thread. 121.It Xo 122.Ft int 123.Fn pthread_setcancelstate "int state" "int *oldstate" 124.Xc 125Sets the current thread's cancelability state. 126.It Xo 127.Ft int 128.Fn pthread_setcanceltype "int type" "int *oldtype" 129.Xc 130Sets the current thread's cancelability type. 131.It Xo 132.Ft void 133.Fn pthread_testcancel void 134.Xc 135Creates a cancellation point in the calling thread. 136.It Xo 137.Ft void 138.Fn pthread_yield void 139.Xc 140Allows the scheduler to run another thread instead of the current one. 141.El 142.Ss Attribute Object Routines 143.Bl -tag -width indent 144.It Xo 145.Ft int 146.Fn pthread_attr_destroy "pthread_attr_t *attr" 147.Xc 148Destroy a thread attributes object. 149.It Xo 150.Ft int 151.Fo pthread_attr_getinheritsched 152.Fa "const pthread_attr_t *attr" "int *inheritsched" 153.Fc 154.Xc 155Get the inherit scheduling attribute from a thread attributes object. 156.It Xo 157.Ft int 158.Fo pthread_attr_getschedparam 159.Fa "const pthread_attr_t *attr" "struct sched_param *param" 160.Fc 161.Xc 162Get the scheduling parameter attribute from a thread attributes object. 163.It Xo 164.Ft int 165.Fn pthread_attr_getschedpolicy "const pthread_attr_t *attr" "int *policy" 166.Xc 167Get the scheduling policy attribute from a thread attributes object. 168.It Xo 169.Ft int 170.Fn pthread_attr_getscope "const pthread_attr_t *attr" "int *contentionscope" 171.Xc 172Get the contention scope attribute from a thread attributes object. 173.It Xo 174.Ft int 175.Fn pthread_attr_getstacksize "const pthread_attr_t *attr" "size_t *stacksize" 176.Xc 177Get the stack size attribute from a thread attributes object. 178.It Xo 179.Ft int 180.Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr" 181.Xc 182Get the stack address attribute from a thread attributes object. 183.It Xo 184.Ft int 185.Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate" 186.Xc 187Get the detach state attribute from a thread attributes object. 188.It Xo 189.Ft int 190.Fn pthread_attr_init "pthread_attr_t *attr" 191.Xc 192Initialize a thread attributes object with default values. 193.It Xo 194.Ft int 195.Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched" 196.Xc 197Set the inherit scheduling attribute in a thread attributes object. 198.It Xo 199.Ft int 200.Fo pthread_attr_setschedparam 201.Fa "pthread_attr_t *attr" "const struct sched_param *param" 202.Fc 203.Xc 204Set the scheduling parameter attribute in a thread attributes object. 205.It Xo 206.Ft int 207.Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy" 208.Xc 209Set the scheduling policy attribute in a thread attributes object. 210.It Xo 211.Ft int 212.Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope" 213.Xc 214Set the contention scope attribute in a thread attributes object. 215.It Xo 216.Ft int 217.Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize" 218.Xc 219Set the stack size attribute in a thread attributes object. 220.It Xo 221.Ft int 222.Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr" 223.Xc 224Set the stack address attribute in a thread attributes object. 225.It Xo 226.Ft int 227.Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate" 228.Xc 229Set the detach state in a thread attributes object. 230.El 231.Ss Mutex Routines 232.Bl -tag -width indent 233.It Xo 234.Ft int 235.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr" 236.Xc 237Destroy a mutex attributes object. 238.It Xo 239.Ft int 240.Fn pthread_mutexattr_getprioceiling "pthread_mutexattr_t *attr" "int *ceiling" 241.Xc 242Obtain priority ceiling attribute of mutex attribute object. 243.It Xo 244.Ft int 245.Fn pthread_mutexattr_getprotocol "pthread_mutexattr_t *attr" "int *protocol" 246.Xc 247Obtain protocol attribute of mutex attribute object. 248.It Xo 249.Ft int 250.Fn pthread_mutexattr_gettype "pthread_mutexattr_t *attr" "int *type" 251.Xc 252Obtain the mutex type attribute in the specified mutex attributes object. 253.It Xo 254.Ft int 255.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr" 256.Xc 257Initialize a mutex attributes object with default values. 258.It Xo 259.Ft int 260.Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int ceiling" 261.Xc 262Set priority ceiling attribute of mutex attribute object. 263.It Xo 264.Ft int 265.Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol" 266.Xc 267Set protocol attribute of mutex attribute object. 268.It Xo 269.Ft int 270.Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type" 271.Xc 272Set the mutex type attribute that is used when a mutex is created. 273.It Xo 274.Ft int 275.Fn pthread_mutex_destroy "pthread_mutex_t *mutex" 276.Xc 277Destroy a mutex. 278.It Xo 279.Ft int 280.Fo pthread_mutex_init 281.Fa "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr" 282.Fc 283.Xc 284Initialize a mutex with specified attributes. 285.It Xo 286.Ft int 287.Fn pthread_mutex_lock "pthread_mutex_t *mutex" 288.Xc 289Lock a mutex and block until it becomes available. 290.It Xo 291.Ft int 292.Fo pthread_mutex_timedlock 293.Fa "pthread_mutex_t *mutex" "const struct timespec *abstime" 294.Fc 295.Xc 296Lock a mutex and block until it becomes available or until the timeout expires. 297.It Xo 298.Ft int 299.Fn pthread_mutex_trylock "pthread_mutex_t *mutex" 300.Xc 301Try to lock a mutex, but do not block if the mutex is locked by another thread, 302including the current thread. 303.It Xo 304.Ft int 305.Fn pthread_mutex_unlock "pthread_mutex_t *mutex" 306.Xc 307Unlock a mutex. 308.El 309.Ss Condition Variable Routines 310.Bl -tag -width indent 311.It Xo 312.Ft int 313.Fn pthread_condattr_destroy "pthread_condattr_t *attr" 314.Xc 315Destroy a condition variable attributes object. 316.It Xo 317.Ft int 318.Fn pthread_condattr_init "pthread_condattr_t *attr" 319.Xc 320Initialize a condition variable attributes object with default values. 321.It Xo 322.Ft int 323.Fn pthread_cond_broadcast "pthread_cond_t *cond" 324.Xc 325Unblock all threads currently blocked on the specified condition variable. 326.It Xo 327.Ft int 328.Fn pthread_cond_destroy "pthread_cond_t *cond" 329.Xc 330Destroy a condition variable. 331.It Xo 332.Ft int 333.Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr" 334.Xc 335Initialize a condition variable with specified attributes. 336.It Xo 337.Ft int 338.Fn pthread_cond_signal "pthread_cond_t *cond" 339.Xc 340Unblock at least one of the threads blocked on the specified condition variable. 341.It Xo 342.Ft int 343.Fo pthread_cond_timedwait 344.Fa "pthread_cond_t *cond" "pthread_mutex_t *mutex" 345.Fa "const struct timespec *abstime" 346.Fc 347.Xc 348Wait no longer than the specified time for a condition 349and lock the specified mutex. 350.It Xo 351.Ft int 352.Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex" 353.Xc 354Wait for a condition and lock the specified mutex. 355.El 356.Ss Read/Write Lock Routines 357.Bl -tag -width indent 358.It Xo 359.Ft int 360.Fn pthread_rwlock_destroy "pthread_rwlock_t *lock" 361.Xc 362Destroy a read/write lock object. 363.It Xo 364.Ft int 365.Fo pthread_rwlock_init 366.Fa "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr" 367.Fc 368.Xc 369Initialize a read/write lock object. 370.It Xo 371.Ft int 372.Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock" 373.Xc 374Lock a read/write lock for reading, blocking until the lock can be 375acquired. 376.It Xo 377.Ft int 378.Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock" 379.Xc 380Attempt to lock a read/write lock for reading, without blocking if the 381lock is unavailable. 382.It Xo 383.Ft int 384.Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock" 385.Xc 386Attempt to lock a read/write lock for writing, without blocking if the 387lock is unavailable. 388.It Xo 389.Ft int 390.Fn pthread_rwlock_unlock "pthread_rwlock_t *lock" 391.Xc 392Unlock a read/write lock. 393.It Xo 394.Ft int 395.Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock" 396.Xc 397Lock a read/write lock for writing, blocking until the lock can be 398acquired. 399.It Xo 400.Ft int 401.Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr" 402.Xc 403Destroy a read/write lock attribute object. 404.It Xo 405.Ft int 406.Fo pthread_rwlockattr_getpshared 407.Fa "const pthread_rwlockattr_t *attr" "int *pshared" 408.Fc 409.Xc 410Retrieve the process shared setting for the read/write lock attribute 411object. 412.It Xo 413.Ft int 414.Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr" 415.Xc 416Initialize a read/write lock attribute object. 417.It Xo 418.Ft int 419.Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared" 420.Xc 421Set the process shared setting for the read/write lock attribute object. 422.El 423.Ss Per-Thread Context Routines 424.Bl -tag -width indent 425.It Xo 426.Ft int 427.Fn pthread_key_create "pthread_key_t *key" "void \*[lp]*routine\*[rp]\*[lp]void *\*[rp]" 428.Xc 429Create a thread-specific data key. 430.It Xo 431.Ft int 432.Fn pthread_key_delete "pthread_key_t key" 433.Xc 434Delete a thread-specific data key. 435.It Xo 436.Ft "void *" 437.Fn pthread_getspecific "pthread_key_t key" 438.Xc 439Get the thread-specific value for the specified key. 440.It Xo 441.Ft int 442.Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr" 443.Xc 444Set the thread-specific value for the specified key. 445.El 446.Ss Cleanup Routines 447.Bl -tag -width indent 448.It Xo 449.Ft int 450.Fo pthread_atfork 451.Fa "void \*[lp]*prepare\*[rp]\*[lp]void\*[rp]" 452.Fa "void \*[lp]*parent\*[rp]\*[lp]void\*[rp]" 453.Fa "void \*[lp]*child\*[rp]\*[lp]void\*[rp]" 454.Fc 455.Xc 456Register fork handlers 457.It Xo 458.Ft void 459.Fn pthread_cleanup_pop "int execute" 460.Xc 461Remove the routine at the top of the calling thread's cancellation cleanup 462stack and optionally invoke it. 463.It Xo 464.Ft void 465.Fn pthread_cleanup_push "void \*[lp]*routine\*[rp]\*[lp]void *\*[rp]" "void *routine_arg" 466.Xc 467Push the specified cancellation cleanup handler onto the calling thread's 468cancellation stack. 469.El 470.Sh IMPLEMENTATION NOTES 471The current 472.Dx 473POSIX thread implementation is built in the library 474.Fa libc_r 475which contains both thread-safe libc functions and the thread functions. 476This library replaces 477.Fa libc 478for threaded applications. 479.Pp 480By default, 481.Fa libc_r 482is built as part of a 'make world'. To disable the build of 483.Fa libc_r 484you must supply the '-DNOLIBC_R' option to 485.Xr make 1 . 486.Pp 487A 488.Fx 489and 490.Dx 491specific option exists in 492.Xr gcc 1 493to simplify the linking of threaded processes. 494.Fa gcc -pthread 495links a threaded process against 496.Fa libc_r 497instead of 498.Fa libc . 499.Sh SEE ALSO 500.Xr pthread_atfork 3 , 501.Xr pthread_cancel 3 , 502.Xr pthread_cleanup_pop 3 , 503.Xr pthread_cleanup_push 3 , 504.Xr pthread_condattr_destroy 3 , 505.Xr pthread_condattr_init 3 , 506.Xr pthread_cond_broadcast 3 , 507.Xr pthread_cond_destroy 3 , 508.Xr pthread_cond_init 3 , 509.Xr pthread_cond_signal 3 , 510.Xr pthread_cond_timedwait 3 , 511.Xr pthread_cond_wait 3 , 512.Xr pthread_create 3 , 513.Xr pthread_detach 3 , 514.Xr pthread_equal 3 , 515.Xr pthread_exit 3 , 516.Xr pthread_getspecific 3 , 517.Xr pthread_join 3 , 518.Xr pthread_key_delete 3 , 519.Xr pthread_kill 3 , 520.Xr pthread_mutexattr_destroy 3 , 521.Xr pthread_mutexattr_getprioceiling 3 , 522.Xr pthread_mutexattr_getprotocol 3 , 523.Xr pthread_mutexattr_gettype 3 , 524.Xr pthread_mutexattr_init 3 , 525.Xr pthread_mutexattr_setprioceiling 3 , 526.Xr pthread_mutexattr_setprotocol 3 , 527.Xr pthread_mutexattr_settype 3 , 528.Xr pthread_mutex_destroy 3 , 529.Xr pthread_mutex_init 3 , 530.Xr pthread_mutex_lock 3 , 531.Xr pthread_mutex_trylock 3 , 532.Xr pthread_mutex_unlock 3 , 533.Xr pthread_once 3 , 534.Xr pthread_rwlockattr_destroy 3 , 535.Xr pthread_rwlockattr_getpshared 3 , 536.Xr pthread_rwlockattr_init 3 , 537.Xr pthread_rwlockattr_setpshared 3 , 538.Xr pthread_rwlock_destroy 3 , 539.Xr pthread_rwlock_init 3 , 540.Xr pthread_rwlock_rdlock 3 , 541.Xr pthread_rwlock_unlock 3 , 542.Xr pthread_rwlock_wrlock 3 , 543.Xr pthread_self 3 , 544.Xr pthread_setcancelstate 3 , 545.Xr pthread_setcanceltype 3 , 546.Xr pthread_setspecific 3 , 547.Xr pthread_testcancel 3 548.Sh STANDARDS 549The functions with the 550.Nm pthread_ 551prefix and not 552.Nm _np 553suffix or 554.Nm pthread_rwlock 555prefix conform to 556.St -p1003.1-96 . 557.Pp 558The functions with the 559.Nm pthread_ 560prefix and 561.Nm _np 562suffix are non-portable extensions to POSIX threads. 563.Pp 564The functions with the 565.Nm pthread_rwlock 566prefix are extensions created by The Open Group as part of the 567.St -susv2 . 568