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