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