1.\" $OpenBSD: pthreads.3,v 1.29 2008/12/18 09:30:32 guenther Exp $ 2.\" David Leonard <d@openbsd.org>, 1998. Public domain. 3.Dd $Mdocdate: December 18 2008 $ 4.Dt PTHREADS 3 5.Os 6.Sh NAME 7.Nm pthreads 8.Nd POSIX 1003.1c thread interface 9.Sh DESCRIPTION 10A thread is a flow of control within a process. 11Each thread represents a minimal amount of state; 12normally just the CPU state and a signal mask. 13All other process state (such as memory, file descriptors) 14is shared among all of the threads in the process. 15.Pp 16In 17.Ox , 18threads are implemented in a user-level library. 19A program using these routines must be linked with the 20.Fl pthread 21option. 22.Pp 23The 24.Dv SIGINFO 25signal can be sent to a threaded process to have the library show the state of 26all of its threads. 27The information is sent to the process' 28controlling tty and describes each thread's 29ID, 30state (see 31.Sx Thread states ) , 32current priority, 33flags (see 34.Sx Thread flags ) , 35signal mask, and name (as set by 36.Xr pthread_set_name_np 3 ) . 37If the environment variable 38.Ev PTHREAD_DEBUG 39is defined additional information is displayed. 40.Pp 41For the purpose of this document, 42the functions available are grouped in the following categories. 43For further information, see the individual man page for each function. 44.Pp 45.Bl -dash -offset indent -compact 46.It 47Attribute Object Routines 48.It 49Cleanup Routines 50.It 51Condition Variable Routines 52.It 53Mutex Routines 54.It 55Non Portable Extensions 56.It 57Per-Thread Context Routines 58.It 59Read/Write Lock Routines 60.It 61Thread Routines 62.El 63.Ss Attribute Object Routines 64The functions available are as follows: 65.Pp 66.Bl -tag -width "pthread_attr_getdetachstate()" -compact 67.It Fn pthread_attr_init 68Initialise a threads attribute object. 69.It Fn pthread_attr_destroy 70Destroy a threads attribute object. 71.It Fn pthread_attr_getdetachstate 72Get detachstate attribute. 73.It Fn pthread_attr_setdetachstate 74Set detachstate attribute. 75.It Fn pthread_attr_getstack 76Get stackaddr and stacksize attributes. 77.It Fn pthread_attr_setstack 78Set stackaddr and stacksize attributes. 79.It Fn pthread_attr_getstackaddr 80Get stackaddr attribute. 81.It Fn pthread_attr_setstackaddr 82Set stackaddr attribute. 83.It Fn pthread_attr_getstacksize 84Get stacksize attribute. 85.It Fn pthread_attr_setstacksize 86Set stacksize attribute. 87.It Fn pthread_attr_getguardsize 88Get guardsize attribute. 89.It Fn pthread_attr_setguardsize 90Set guardsize attribute. 91.El 92.Ss Cleanup Routines 93The functions available are as follows: 94.Pp 95.Bl -tag -width "pthread_cleanup_push()" -compact 96.It Fn pthread_atfork 97Register fork handlers. 98.It Fn pthread_cleanup_pop 99Call the first cleanup routine. 100.It Fn pthread_cleanup_push 101Add a cleanup function for thread exit. 102.El 103.Ss Condition Variable Routines 104The functions available are as follows: 105.Pp 106.Bl -tag -width "pthread_cond_timedwait()" -compact 107.It Fn pthread_cond_broadcast 108Unblock all threads waiting for a condition variable. 109.It Fn pthread_cond_destroy 110Destroy a condition variable. 111.It Fn pthread_cond_init 112Create a condition variable. 113.It Fn pthread_cond_signal 114Unblock a thread waiting for a condition variable. 115.It Fn pthread_cond_timedwait 116Wait on a condition variable for a specific amount of time. 117.It Fn pthread_cond_wait 118Wait on a condition variable. 119.El 120.Ss Mutex Routines 121The functions available are as follows: 122.Pp 123.Bl -tag -width "pthread_mutexattr_getprioceiling()" -compact 124.It Fn pthread_mutex_destroy 125Free resources allocated for a mutex. 126.It Fn pthread_mutex_init 127Create a mutex. 128.It Fn pthread_mutex_lock 129Lock a mutex. 130.It Fn pthread_mutex_trylock 131Attempt to lock a mutex without blocking. 132.It Fn pthread_mutex_unlock 133Unlock a mutex. 134.It Fn pthread_mutexattr_init 135Mutex attribute operations. 136.It Fn pthread_mutexattr_destroy 137Mutex attribute operations. 138.It Fn pthread_mutexattr_getprioceiling 139Mutex attribute operations. 140.It Fn pthread_mutexattr_setprioceiling 141Mutex attribute operations. 142.It Fn pthread_mutexattr_getprotocol 143Mutex attribute operations. 144.It Fn pthread_mutexattr_setprotocol 145Mutex attribute operations. 146.It Fn pthread_mutexattr_gettype 147Mutex attribute operations. 148.It Fn pthread_mutexattr_settype 149Mutex attribute operations. 150.El 151.Ss Non Portable Extensions 152The functions available are as follows: 153.Pp 154.Bl -tag -width "pthread_suspend_all_np()" -compact 155.It Fn pthread_main_np 156Identify the main thread. 157.It Fn pthread_set_name_np 158Set the name of a thread. 159.It Fn pthread_single_np 160Switch thread scheduling mode. 161.It Fn pthread_multi_np 162Switch thread scheduling mode. 163.It Fn pthread_stackseg_np 164Return stack size and location. 165.It Fn pthread_suspend_np 166Suspend given thread. 167.It Fn pthread_suspend_all_np 168Suspend all threads except current thread. 169.It Fn pthread_resume_np 170Resumes given thread. 171.It Fn pthread_resume_all_np 172Resumes all suspended threads. 173.It Fn pthread_yield 174Yield control of the current thread. 175.El 176.Ss Per-Thread Context Routines 177The functions available are as follows: 178.Pp 179.Bl -tag -width "pthread_getspecific()" -compact 180.It Fn pthread_key_create 181Thread-specific data key creation. 182.It Fn pthread_key_delete 183Delete a thread-specific data key. 184.It Fn pthread_getspecific 185Get a thread-specific data value. 186.It Fn pthread_setspecific 187Set a thread-specific data value. 188.El 189.Ss Read/Write Lock Routines 190The functions available are as follows: 191.Pp 192.Bl -tag -width "pthread_rwlockattr_getpshared()" -compact 193.It Fn pthread_rwlock_destroy 194Destroy a read/write lock. 195.It Fn pthread_rwlock_init 196Initialise a read/write lock. 197.It Fn pthread_rwlock_rdlock 198Acquire a read/write lock for reading. 199.It Fn pthread_rwlock_unlock 200Release a read/write lock. 201.It Fn pthread_rwlock_wrlock 202Acquire a read/write lock for writing. 203.It Fn pthread_rwlockattr_destroy 204Destroy a read/write lock. 205.It Fn pthread_rwlockattr_getpshared 206Get the process shared attribute. 207.It Fn pthread_rwlockattr_init 208Initialise a read/write lock. 209.It Fn pthread_rwlockattr_setpshared 210Set the process shared attribute. 211.El 212.Ss Thread Routines 213The functions available are as follows: 214.Pp 215.Bl -tag -width "pthread_getconcurrency()" -compact 216.It Fn pthread_create 217Create a new thread. 218.It Fn pthread_cancel 219Cancel execution of a thread. 220.It Fn pthread_detach 221Detach a thread. 222.It Fn pthread_equal 223Compare thread IDs. 224.It Fn pthread_exit 225Terminate the calling thread. 226.It Fn pthread_getconcurrency 227Get level of concurrency. 228.It Fn pthread_setconcurrency 229Set level of concurrency. 230.It Fn pthread_join 231Wait for thread termination. 232.It Fn pthread_kill 233Send a signal to a specific thread. 234.It Fn pthread_once 235Dynamic package initialisation. 236.It Fn pthread_self 237Get the calling thread's ID. 238.It Fn pthread_setcancelstate 239Set cancelability state. 240.It Fn pthread_setcanceltype 241Set cancelability state. 242.It Fn pthread_testcancel 243Set cancelability state. 244.It Fn pthread_sigmask 245Examine/change a thread's signal mask. 246.El 247.Ss Thread states 248Threads can be in one of these states: 249.Pp 250.Bl -tag -offset indent -width Dv -compact 251.It cond_wait 252Executing 253.Xr pthread_cond_wait 3 254or 255.Xr pthread_cond_timedwait 3 . 256.It dead 257Waiting for resource deallocation by the thread garbage collector. 258.It deadlock 259Waiting for a resource held by the thread itself. 260.It fdlr_wait 261File descriptor read lock wait. 262.It fdlw_wait 263File descriptor write lock wait. 264.It fdr_wait 265Executing one of 266.Xr accept 2 , 267.Xr read 2 , 268.Xr readv 2 , 269.Xr recvfrom 2 , 270.Xr recvmsg 2 . 271.It fdw_wait 272Executing one of 273.Xr connect 2 , 274.Xr sendmsg 2 , 275.Xr sendto 2 , 276.Xr write 2 , 277.Xr writev 2 . 278.It file_wait 279Executing 280.Xr flockfile 3 281or similar. 282.It join 283Executing 284.Xr pthread_join 3 . 285.It mutex_wait 286Executing 287.Xr pthread_mutex_lock 3 . 288.It poll_wait 289Executing 290.Xr poll 2 . 291.It running 292Scheduled for, or engaged in, program execution. 293.It select_wait 294Executing 295.Xr select 2 . 296.It sigsuspend 297Executing 298.Xr sigsuspend 2 . 299.It sigwait 300Executing 301.Xr sigwait 3 . 302.It sleep_wait 303Executing 304.Xr sleep 3 305or 306.Xr nanosleep 2 . 307.It spinblock 308Waiting for a machine-level atomic lock. 309.It suspended 310Suspended with 311.Xr pthread_suspend_np 3 312or 313.Xr pthread_suspend_all_np 3 . 314.It wait_wait 315Executing 316.Xr wait4 2 317or similar. 318.El 319.Ss Thread flags 320The first three flags are one of: 321.Pp 322.Bl -tag -offset indent -width 3en -compact 323.It "p" 324Private, system thread (e.g., the garbage collector). 325.It "E, C, or c" 326Thread is exiting (E), has a cancellation pending (C) (see 327.Xr pthread_cancel 3 ) , 328or is at a cancellation point (c). 329.It "t" 330Thread is being traced. 331.El 332.Pp 333The next 7 flags refer to thread attributes: 334.Pp 335.Bl -tag -offset indent -width 3en -compact 336.It "C" 337Thread is in the 338.Dv CONDQ . 339.It "R" 340Thread is in the 341.Dv WORKQ . 342.It "W" 343Thread is in the 344.Dv WAITQ . 345.It "P" 346Thread is in the 347.Dv PRIOQ . 348.It "d" 349Thread has been detached (see 350.Xr pthread_detach 3 ) . 351.It "i" 352Thread inherits scheduler properties. 353.It "f" 354Thread will save floating point context. 355.El 356.Ss Scheduling algorithm 357The scheduling algorithm used by the user-level thread library is 358roughly as follows: 359.Pp 360.Bl -enum -compact 361.It 362Threads each have a time slice credit which is debited 363by the actual time the thread spends in running. 364Freshly scheduled threads are given a time slice credit of 100000 usec. 365.It 366Give an incremental priority update to run-enabled threads that 367have not run since the last time that an incremental priority update 368was given to them. 369.It 370Choose the next run-enabled thread with the highest priority, 371that became inactive least recently, and has 372the largest remaining time slice. 373.El 374.Pp 375When all threads are blocked, the process also blocks. 376When there are no threads remaining, 377the process terminates with an exit code of zero. 378.Ss Thread stacks 379Each thread has (or should have) a different stack, whether it be provided by a 380user attribute, or provided automatically by the system. 381If a thread overflows its stack, unpredictable results may occur. 382System-allocated stacks (including that of the initial thread) 383are typically allocated in such a way that a 384.Dv SIGSEGV 385signal is delivered to the process when a stack overflows. 386.Pp 387Signals handlers are normally run on the stack of the currently executing 388thread. 389Hence, if you want to handle the 390.Dv SIGSEGV 391signal, you should make use of 392.Xr sigaltstack 2 393or 394.Xr sigprocmask 2 . 395.Ss Thread safety 396The following functions are not thread safe: 397.Bd -filled 398asctime(), 399basename(), 400catgets(), 401crypt(), 402ctime(), 403dbm_clearerr(), 404dbm_close(), 405dbm_delete(), 406dbm_error(), 407dbm_fetch(), 408dbm_firstkey(), 409dbm_nextkey(), 410dbm_open(), 411dbm_store(), 412dirname(), 413dlerror(), 414drand48(), 415ecvt(), 416encrypt(), 417endgrent(), 418endpwent(), 419fcvt(), 420ftw(), 421gcvt(), 422getc_unlocked(), 423getchar_unlocked(), 424getenv(), 425getgrent(), 426getgrgid(), 427getgrnam(), 428gethostbyaddr(), 429gethostbyname(), 430gethostent(), 431getlogin(), 432getnetbyaddr(), 433getnetbyname(), 434getnetent(), 435getopt(), 436getprotobyname(), 437getprotobynumber(), 438getprotoent(), 439getpwent(), 440getpwnam(), 441getpwuid(), 442getservbyname(), 443getservbyport(), 444getservent(), 445gmtime(), 446hcreate(), 447hdestroy(), 448hsearch(), 449inet_ntoa(), 450l64a(), 451lgamma(), 452lgammaf(), 453localeconv(), 454localtime(), 455lrand48(), 456mrand48(), 457nftw(), 458nl_langinfo(), 459putc_unlocked(), 460putchar_unlocked(), 461putenv(), 462rand(), 463readdir(), 464setenv(), 465setgrent(), 466setkey(), 467setpwent(), 468strerror(), 469strtok(), 470ttyname(), 471unsetenv(), 472.Ed 473.Pp 474The 475.Fn ctermid 476and 477.Fn tmpnam 478functions are not thread safe when passed a 479.Dv NULL 480argument. 481.Sh ENVIRONMENT 482.Bl -tag -width "LIBPTHREAD_DEBUG" 483.It Ev PTHREAD_DEBUG 484Enables verbose 485.Dv SIGINFO 486signal output. 487.It Ev LIBPTHREAD_DEBUG 488Display thread status every time the garbage collection thread runs, 489approximately once every 10 seconds. 490The status display verbosity is controlled by the 491.Ev PTHREAD_DEBUG 492environment variable. 493.El 494.Sh SEE ALSO 495.Xr pthread_atfork 3 , 496.Xr pthread_attr_init 3 , 497.Xr pthread_attr_setdetachstate 3 , 498.Xr pthread_attr_setguardsize 3 , 499.Xr pthread_attr_setstack 3 , 500.Xr pthread_attr_setstackaddr 3 , 501.Xr pthread_attr_setstacksize 3 , 502.Xr pthread_cancel 3 , 503.Xr pthread_cleanup_pop 3 , 504.Xr pthread_cleanup_push 3 , 505.Xr pthread_cond_broadcast 3 , 506.Xr pthread_cond_destroy 3 , 507.Xr pthread_cond_init 3 , 508.Xr pthread_cond_signal 3 , 509.Xr pthread_cond_timedwait 3 , 510.Xr pthread_cond_wait 3 , 511.Xr pthread_create 3 , 512.Xr pthread_detach 3 , 513.Xr pthread_equal 3 , 514.Xr pthread_exit 3 , 515.Xr pthread_getspecific 3 , 516.Xr pthread_join 3 , 517.Xr pthread_key_create 3 , 518.Xr pthread_key_delete 3 , 519.Xr pthread_kill 3 , 520.Xr pthread_main_np 3 , 521.Xr pthread_mutex_destroy 3 , 522.Xr pthread_mutex_init 3 , 523.Xr pthread_mutex_lock 3 , 524.Xr pthread_mutex_trylock 3 , 525.Xr pthread_mutex_unlock 3 , 526.Xr pthread_mutexattr 3 , 527.Xr pthread_once 3 , 528.Xr pthread_resume_all_np 3 , 529.Xr pthread_resume_np 3 , 530.Xr pthread_rwlock_destroy 3 , 531.Xr pthread_rwlock_init 3 , 532.Xr pthread_rwlock_rdlock 3 , 533.Xr pthread_rwlock_unlock 3 , 534.Xr pthread_rwlock_wrlock 3 , 535.Xr pthread_rwlockattr_destroy 3 , 536.Xr pthread_rwlockattr_getpshared 3 , 537.Xr pthread_rwlockattr_init 3 , 538.Xr pthread_rwlockattr_setpshared 3 , 539.Xr pthread_schedparam 3 , 540.Xr pthread_self 3 , 541.Xr pthread_set_name_np 3 , 542.Xr pthread_setspecific 3 , 543.Xr pthread_sigmask 3 , 544.Xr pthread_single_np 3 , 545.Xr pthread_stackseg_np 3 , 546.Xr pthread_suspend_all_np 3 , 547.Xr pthread_suspend_np 3 , 548.Xr pthread_testcancel 3 , 549.Xr pthread_yield 3 550.Sh STANDARDS 551The user-level thread library provides functions that 552conform to ISO/IEC 9945-1 ANSI/IEEE 553.Pq Dq Tn POSIX 554Std 1003.1 Second Edition 1996-07-12. 555.Sh AUTHORS 556John Birrell 557.Pa ( jb@freebsd.org ) 558wrote the majority of the user level thread library. 559.\" David Leonard did a fair bit too, but is far too modest. 560.Sh BUGS 561The library contains a scheduler that uses the 562process virtual interval timer to pre-empt running threads. 563This means that using 564.Xr setitimer 2 565to alter the process virtual timer will have undefined effects. 566The 567.Dv SIGVTALRM 568will never be delivered to threads in a process. 569.Pp 570Some pthread functions fail to work correctly when linked using the 571.Fl g 572option to 573.Xr cc 1 574or 575.Xr gcc 1 . 576The problems do not occur when linked using the 577.Fl ggdb 578option. 579