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