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