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