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