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