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 January 15, 2004 34.Dt PTHREAD 3 35.Os 36.Sh NAME 37.Nm pthread 38.Nd POSIX thread functions 39.Sh LIBRARY 40.Lb libpthread 41.Lb libthr 42.Lb libc_r 43.Sh SYNOPSIS 44.In pthread.h 45.Sh DESCRIPTION 46POSIX threads are a set of functions that support applications with 47requirements for multiple flows of control, called 48.Em threads , 49within a process. 50Multithreading is used to improve the performance of a 51program. 52.Pp 53The POSIX thread functions are summarized in this section in the following 54groups: 55.Pp 56.Bl -bullet -offset indent -compact 57.It 58Thread Routines 59.It 60Attribute Object Routines 61.It 62Mutex Routines 63.It 64Condition Variable Routines 65.It 66Read/Write Lock 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 *\*[lp]*start_routine\*[rp]\*[lp]void *\*[rp]" "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 \*[lp]*init_routine\*[rp]\*[lp]void\*[rp]" 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 don't 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 Per-Thread Context Routines 425.Bl -tag -width indent 426.It Xo 427.Ft int 428.Fn pthread_key_create "pthread_key_t *key" "void \*[lp]*routine\*[rp]\*[lp]void *\*[rp]" 429.Xc 430Create a thread-specific data key. 431.It Xo 432.Ft int 433.Fn pthread_key_delete "pthread_key_t key" 434.Xc 435Delete a thread-specific data key. 436.It Xo 437.Ft "void *" 438.Fn pthread_getspecific "pthread_key_t key" 439.Xc 440Get the thread-specific value for the specified key. 441.It Xo 442.Ft int 443.Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr" 444.Xc 445Set the thread-specific value for the specified key. 446.El 447.Ss Cleanup Routines 448.Bl -tag -width indent 449.It Xo 450.Ft void 451.Fn pthread_cleanup_pop "int execute" 452.Xc 453Remove the routine at the top of the calling thread's cancellation cleanup 454stack and optionally invoke it. 455.It Xo 456.Ft void 457.Fn pthread_cleanup_push "void \*[lp]*routine\*[rp]\*[lp]void *\*[rp]" "void *routine_arg" 458.Xc 459Push the specified cancellation cleanup handler onto the calling thread's 460cancellation stack. 461.El 462.Sh INSTALLATION 463The current 464.Fx 465POSIX thread implementation is built in three libraries, 466.Lb libc_r , 467.Lb libpthread , 468and 469.Lb libthr . 470They contain both thread-safe versions of 471.Lb libc 472functions and the thread functions. 473Threaded applications are linked with one of these libraries. 474.Sh SEE ALSO 475.Xr pthread_cleanup_pop 3 , 476.Xr pthread_cleanup_push 3 , 477.Xr pthread_condattr_destroy 3 , 478.Xr pthread_condattr_init 3 , 479.Xr pthread_cond_broadcast 3 , 480.Xr pthread_cond_destroy 3 , 481.Xr pthread_cond_init 3 , 482.Xr pthread_cond_signal 3 , 483.Xr pthread_cond_timedwait 3 , 484.Xr pthread_cond_wait 3 , 485.Xr pthread_create 3 , 486.Xr pthread_detach 3 , 487.Xr pthread_equal 3 , 488.Xr pthread_exit 3 , 489.Xr pthread_getspecific 3 , 490.Xr pthread_join 3 , 491.Xr pthread_key_delete 3 , 492.Xr pthread_kill 3 , 493.Xr pthread_mutexattr_destroy 3 , 494.Xr pthread_mutexattr_getprioceiling 3 , 495.Xr pthread_mutexattr_getprotocol 3 , 496.Xr pthread_mutexattr_gettype 3 , 497.Xr pthread_mutexattr_init 3 , 498.Xr pthread_mutexattr_setprioceiling 3 , 499.Xr pthread_mutexattr_setprotocol 3 , 500.Xr pthread_mutexattr_settype 3 , 501.Xr pthread_mutex_destroy 3 , 502.Xr pthread_mutex_init 3 , 503.Xr pthread_mutex_lock 3 , 504.Xr pthread_mutex_trylock 3 , 505.Xr pthread_mutex_unlock 3 , 506.Xr pthread_once 3 , 507.Xr pthread_rwlockattr_destroy 3 , 508.Xr pthread_rwlockattr_getpshared 3 , 509.Xr pthread_rwlockattr_init 3 , 510.Xr pthread_rwlockattr_setpshared 3 , 511.Xr pthread_rwlock_destroy 3 , 512.Xr pthread_rwlock_init 3 , 513.Xr pthread_rwlock_rdlock 3 , 514.Xr pthread_rwlock_unlock 3 , 515.Xr pthread_rwlock_wrlock 3 , 516.Xr pthread_self 3 , 517.Xr pthread_setcancelstate 3 , 518.Xr pthread_setcanceltype 3 , 519.Xr pthread_setspecific 3 , 520.Xr pthread_testcancel 3 521.Sh STANDARDS 522The functions with the 523.Nm pthread_ 524prefix and not 525.Nm _np 526suffix or 527.Nm pthread_rwlock 528prefix conform to 529.St -p1003.1-96 . 530.Pp 531The functions with the 532.Nm pthread_ 533prefix and 534.Nm _np 535suffix are non-portable extensions to POSIX threads. 536.Pp 537The functions with the 538.Nm pthread_rwlock 539prefix are extensions created by The Open Group as part of the 540.St -susv2 . 541