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