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