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.Dd October 12, 2021 32.Dt PTHREAD 3 33.Os 34.Sh NAME 35.Nm pthread 36.Nd POSIX thread functions 37.Sh LIBRARY 38.Lb libpthread 39.Sh SYNOPSIS 40.In pthread.h 41.Sh DESCRIPTION 42POSIX threads are a set of functions that support applications with 43requirements for multiple flows of control, called 44.Em threads , 45within a process. 46Multithreading is used to improve the performance of a 47program. 48.Pp 49The POSIX thread functions are summarized in this section in the following 50groups: 51.Pp 52.Bl -bullet -offset indent -compact 53.It 54Thread Routines 55.It 56Attribute Object Routines 57.It 58Mutex Routines 59.It 60Condition Variable Routines 61.It 62Read/Write Lock Routines 63.It 64Per-Thread Context Routines 65.It 66Cleanup Routines 67.El 68.Pp 69.Fx 70extensions to the POSIX thread functions are summarized in 71.Xr pthread_np 3 . 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 "const pthread_mutexattr_t *restrict attr" "int *restrict ceiling" 242.Xc 243Obtain priority ceiling attribute of mutex attribute object. 244.It Xo 245.Ft int 246.Fn pthread_mutexattr_getprotocol "const pthread_mutexattr_t *restrict attr" "int *restrict protocol" 247.Xc 248Obtain protocol attribute of mutex attribute object. 249.It Xo 250.Ft int 251.Fn pthread_mutexattr_gettype "const pthread_mutexattr_t *restrict attr" "int *restrict 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 349Unlock the specified mutex, wait no longer than the specified time for 350a condition, and then relock the mutex. 351.It Xo 352.Ft int 353.Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex" 354.Xc 355Unlock the specified mutex, wait for a condition, and relock the 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 int 451.Fo pthread_atfork 452.Fa "void \*[lp]*prepare\*[rp]\*[lp]void\*[rp]" 453.Fa "void \*[lp]*parent\*[rp]\*[lp]void\*[rp]" 454.Fa "void \*[lp]*child\*[rp]\*[lp]void\*[rp]" 455.Fc 456.Xc 457Register fork handlers. 458.It Xo 459.Ft void 460.Fn pthread_cleanup_pop "int execute" 461.Xc 462Remove the routine at the top of the calling thread's cancellation cleanup 463stack and optionally invoke it. 464.It Xo 465.Ft void 466.Fn pthread_cleanup_push "void \*[lp]*routine\*[rp]\*[lp]void *\*[rp]" "void *routine_arg" 467.Xc 468Push the specified cancellation cleanup handler onto the calling thread's 469cancellation stack. 470.El 471.Sh IMPLEMENTATION NOTES 472The current 473.Fx 474POSIX thread implementation is built into the 475.Lb libthr 476library. 477It contains thread-safe versions of 478.Lb libc 479functions and the thread functions. 480Threaded applications are linked with this library. 481.Sh SEE ALSO 482.Xr libthr 3 , 483.Xr pthread_atfork 3 , 484.Xr pthread_attr 3 , 485.Xr pthread_cancel 3 , 486.Xr pthread_cleanup_pop 3 , 487.Xr pthread_cleanup_push 3 , 488.Xr pthread_cond_broadcast 3 , 489.Xr pthread_cond_destroy 3 , 490.Xr pthread_cond_init 3 , 491.Xr pthread_cond_signal 3 , 492.Xr pthread_cond_timedwait 3 , 493.Xr pthread_cond_wait 3 , 494.Xr pthread_condattr_destroy 3 , 495.Xr pthread_condattr_init 3 , 496.Xr pthread_create 3 , 497.Xr pthread_detach 3 , 498.Xr pthread_equal 3 , 499.Xr pthread_exit 3 , 500.Xr pthread_getspecific 3 , 501.Xr pthread_join 3 , 502.Xr pthread_key_delete 3 , 503.Xr pthread_kill 3 , 504.Xr pthread_mutex_destroy 3 , 505.Xr pthread_mutex_init 3 , 506.Xr pthread_mutex_lock 3 , 507.Xr pthread_mutex_trylock 3 , 508.Xr pthread_mutex_unlock 3 , 509.Xr pthread_mutexattr_destroy 3 , 510.Xr pthread_mutexattr_getprioceiling 3 , 511.Xr pthread_mutexattr_getprotocol 3 , 512.Xr pthread_mutexattr_gettype 3 , 513.Xr pthread_mutexattr_init 3 , 514.Xr pthread_mutexattr_setprioceiling 3 , 515.Xr pthread_mutexattr_setprotocol 3 , 516.Xr pthread_mutexattr_settype 3 , 517.Xr pthread_np 3 , 518.Xr pthread_once 3 , 519.Xr pthread_rwlock_destroy 3 , 520.Xr pthread_rwlock_init 3 , 521.Xr pthread_rwlock_rdlock 3 , 522.Xr pthread_rwlock_unlock 3 , 523.Xr pthread_rwlock_wrlock 3 , 524.Xr pthread_rwlockattr_destroy 3 , 525.Xr pthread_rwlockattr_getpshared 3 , 526.Xr pthread_rwlockattr_init 3 , 527.Xr pthread_rwlockattr_setpshared 3 , 528.Xr pthread_self 3 , 529.Xr pthread_setcancelstate 3 , 530.Xr pthread_setcanceltype 3 , 531.Xr pthread_setspecific 3 , 532.Xr pthread_testcancel 3 533.Sh STANDARDS 534The functions with the 535.Nm pthread_ 536prefix and not 537.Nm _np 538suffix or 539.Nm pthread_rwlock 540prefix conform to 541.St -p1003.1-96 . 542.Pp 543The functions with the 544.Nm pthread_ 545prefix and 546.Nm _np 547suffix are non-portable extensions to POSIX threads. 548.Pp 549The functions with the 550.Nm pthread_rwlock 551prefix are extensions created by The Open Group as part of the 552.St -susv2 . 553