1.\" $OpenBSD: pthreads.3,v 1.38 2012/09/02 13:29:29 jmc Exp $ 2.\" David Leonard <d@openbsd.org>, 1998. Public domain. 3.Dd $Mdocdate: September 2 2012 $ 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 use a 1-to-1 implementation, 19where every thread is independently scheduled by the kernel. 20.Pp 21For the purpose of this document, 22the functions available are grouped in the following categories. 23For further information, see the individual man page for each function. 24.Pp 25.Bl -dash -offset indent -compact 26.It 27Attribute Object Routines 28.It 29Barrier Routines 30.It 31Cleanup Routines 32.It 33Condition Variable Routines 34.It 35Mutex Routines 36.It 37Non Portable Extensions 38.It 39Per-Thread Context Routines 40.It 41Read/Write Lock Routines 42.It 43Spinlock Routines 44.It 45Thread Routines 46.El 47.Ss Attribute Object Routines 48The functions available are as follows: 49.Pp 50.Bl -tag -width "pthread_attr_getdetachstate()" -compact 51.It Fn pthread_attr_init 52Initialise a threads attribute object. 53.It Fn pthread_attr_destroy 54Destroy a threads attribute object. 55.It Fn pthread_attr_getdetachstate 56Get detachstate attribute. 57.It Fn pthread_attr_setdetachstate 58Set detachstate attribute. 59.It Fn pthread_attr_getstack 60Get stackaddr and stacksize attributes. 61.It Fn pthread_attr_setstack 62Set stackaddr and stacksize attributes. 63.It Fn pthread_attr_getstackaddr 64Get stackaddr attribute. 65.It Fn pthread_attr_setstackaddr 66Set stackaddr attribute. 67.It Fn pthread_attr_getstacksize 68Get stacksize attribute. 69.It Fn pthread_attr_setstacksize 70Set stacksize attribute. 71.It Fn pthread_attr_getguardsize 72Get guardsize attribute. 73.It Fn pthread_attr_setguardsize 74Set guardsize attribute. 75.El 76.Ss Barrier Routines 77The functions available are as follows: 78.Pp 79.Bl -tag -width "pthread_barrierattr_getpshared()" -compact 80.It Fn pthread_barrier_init 81Initialize a barrier object. 82.It Fn pthread_barrier_destroy 83Destroy a barrier object. 84.It Fn pthread_barrier_wait 85Synchronize at a barrier. 86.It Fn pthread_barrierattr_init 87Initialize a barrier's attribute object. 88.It Fn pthread_barrierattr_destroy 89Destroy a barrier's attribute object. 90.It Fn pthread_barrierattr_getpshared 91Get the process-shared attribute of the barrier attribute's object. 92.It Fn pthread_barrierattr_setpshared 93Set the process-shared attribute of the barrier attribute's object. 94.El 95.Ss Cleanup Routines 96The functions available are as follows: 97.Pp 98.Bl -tag -width "pthread_cleanup_push()" -compact 99.It Fn pthread_atfork 100Register fork handlers. 101.It Fn pthread_cleanup_pop 102Call the first cleanup routine. 103.It Fn pthread_cleanup_push 104Add a cleanup function for thread exit. 105.El 106.Ss Condition Variable Routines 107The functions available are as follows: 108.Pp 109.Bl -tag -width "pthread_condattr_setclock()" -compact 110.It Fn pthread_cond_init 111Create a condition variable. 112.It Fn pthread_cond_destroy 113Destroy a condition variable. 114.It Fn pthread_cond_broadcast 115Unblock all threads waiting for a condition variable. 116.It Fn pthread_cond_signal 117Unblock a thread waiting for a condition variable. 118.It Fn pthread_cond_timedwait 119Wait on a condition variable until a specific point in time. 120.It Fn pthread_cond_wait 121Wait on a condition variable. 122.It Fn pthread_condattr_init 123Initialise a condition variable attribute object. 124.It Fn pthread_condattr_destroy 125Destroy a condition variable attribute object. 126.It Fn pthread_condattr_getclock 127Get clock attribute. 128.It Fn pthread_condattr_setclock 129Set clock attribute. 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_init 136Create a mutex. 137.It Fn pthread_mutex_destroy 138Free resources allocated for a mutex. 139.It Fn pthread_mutex_lock 140Lock a mutex. 141.It Fn pthread_mutex_timedlock 142Attempt to lock a mutex before a specific point in time. 143.It Fn pthread_mutex_trylock 144Attempt to lock a mutex without blocking. 145.It Fn pthread_mutex_unlock 146Unlock a mutex. 147.It Fn pthread_mutexattr_init 148Mutex attribute operations. 149.It Fn pthread_mutexattr_destroy 150Mutex attribute operations. 151.It Fn pthread_mutexattr_getprioceiling 152Mutex attribute operations. 153.It Fn pthread_mutexattr_setprioceiling 154Mutex attribute operations. 155.It Fn pthread_mutexattr_getprotocol 156Mutex attribute operations. 157.It Fn pthread_mutexattr_setprotocol 158Mutex attribute operations. 159.It Fn pthread_mutexattr_gettype 160Mutex attribute operations. 161.It Fn pthread_mutexattr_settype 162Mutex attribute operations. 163.El 164.Ss Non Portable Extensions 165The functions available are as follows: 166.Pp 167.Bl -tag -width "pthread_set_name_np()" -compact 168.It Fn pthread_main_np 169Identify the main thread. 170.It Fn pthread_set_name_np 171Set the name of a thread. 172.It Fn pthread_stackseg_np 173Return stack size and location. 174.It Fn pthread_yield 175Yield control of the current thread. 176.El 177.Ss Per-Thread Context Routines 178The functions available are as follows: 179.Pp 180.Bl -tag -width "pthread_getspecific()" -compact 181.It Fn pthread_key_create 182Thread-specific data key creation. 183.It Fn pthread_key_delete 184Delete a thread-specific data key. 185.It Fn pthread_getspecific 186Get a thread-specific data value. 187.It Fn pthread_setspecific 188Set a thread-specific data value. 189.El 190.Ss Read/Write Lock Routines 191The functions available are as follows: 192.Pp 193.Bl -tag -width "pthread_rwlockattr_getpshared()" -compact 194.It Fn pthread_rwlock_init 195Initialise a read/write lock. 196.It Fn pthread_rwlock_destroy 197Destroy a read/write lock. 198.It Fn pthread_rwlock_rdlock 199Acquire a read/write lock for reading. 200.It Fn pthread_rwlock_timedrdlock 201Attempt to acquire a read/write lock for reading before a specific 202point in time. 203.It Fn pthread_rwlock_tryrdlock 204Attempt to acquire a read/write lock for reading without blocking. 205.It Fn pthread_rwlock_wrlock 206Acquire a read/write lock for writing. 207.It Fn pthread_rwlock_timedwrlock 208Attempt to acquire a read/write lock for writing before a specific 209point in time. 210.It Fn pthread_rwlock_trywrlock 211Attempt to acquire a read/write lock for writing without blocking. 212.It Fn pthread_rwlock_unlock 213Release a read/write lock. 214.It Fn pthread_rwlockattr_init 215Initialise a read/write lock. 216.It Fn pthread_rwlockattr_destroy 217Destroy a read/write lock. 218.It Fn pthread_rwlockattr_getpshared 219Get the process shared attribute. 220.It Fn pthread_rwlockattr_setpshared 221Set the process shared attribute. 222.El 223.Ss Spinlock Routines 224The functions available are as follows: 225.Pp 226.Bl -tag -width "pthread_spin_trylock()" -compact 227.It Fn pthread_spin_init 228Initialize a spinlock object. 229.It Fn pthread_spin_destroy 230Destroy a spinlock object. 231.It Fn pthread_spin_lock 232Lock a spinlock object. 233.It Fn pthread_spin_trylock 234Attempt to lock a spinlock without blocking. 235.It Fn pthread_spin_unlock 236Unlock a spinlock object. 237.El 238.Ss Thread Routines 239The functions available are as follows: 240.Pp 241.Bl -tag -width "pthread_getconcurrency()" -compact 242.It Fn pthread_create 243Create a new thread. 244.It Fn pthread_cancel 245Cancel execution of a thread. 246.It Fn pthread_detach 247Detach a thread. 248.It Fn pthread_equal 249Compare thread IDs. 250.It Fn pthread_exit 251Terminate the calling thread. 252.It Fn pthread_getconcurrency 253Get level of concurrency. 254.It Fn pthread_setconcurrency 255Set level of concurrency. 256.It Fn pthread_join 257Wait for thread termination. 258.It Fn pthread_kill 259Send a signal to a specific thread. 260.It Fn pthread_once 261Dynamic package initialisation. 262.It Fn pthread_self 263Get the calling thread's ID. 264.It Fn pthread_setcancelstate 265Set cancelability state. 266.It Fn pthread_setcanceltype 267Set cancelability state. 268.It Fn pthread_testcancel 269Set cancelability state. 270.It Fn pthread_sigmask 271Examine/change a thread's signal mask. 272.El 273.Ss Thread stacks 274Each thread has a different stack, whether it be provided by a 275user attribute, or provided automatically by the system. 276If a thread overflows its stack, unpredictable results may occur. 277System-allocated stacks (including that of the initial thread) 278are typically allocated in such a way that a 279.Dv SIGSEGV 280signal is delivered to the process when a stack overflows. 281.Pp 282Signals handlers are normally run on the stack of the currently executing 283thread. 284Hence, if you want to handle the 285.Dv SIGSEGV 286signal from stack overflow for a thread, you should use 287.Xr sigaltstack 2 288in that thread. 289.Ss Thread safety 290The following functions are not thread-safe: 291.Bd -filled 292asctime(), 293basename(), 294catgets(), 295crypt(), 296ctime(), 297dbm_clearerr(), 298dbm_close(), 299dbm_delete(), 300dbm_error(), 301dbm_fetch(), 302dbm_firstkey(), 303dbm_nextkey(), 304dbm_open(), 305dbm_store(), 306dirname(), 307dlerror(), 308drand48(), 309ecvt(), 310encrypt(), 311endgrent(), 312endpwent(), 313fcvt(), 314ftw(), 315gcvt(), 316getc_unlocked(), 317getchar_unlocked(), 318.\" getdate(), 319getenv(), 320getgrent(), 321getgrgid(), 322getgrnam(), 323gethostbyaddr(), 324gethostbyname(), 325gethostent(), 326getlogin(), 327getnetbyaddr(), 328getnetbyname(), 329getnetent(), 330getopt(), 331getprotobyname(), 332getprotobynumber(), 333getprotoent(), 334getpwent(), 335getpwnam(), 336getpwuid(), 337getservbyname(), 338getservbyport(), 339getservent(), 340gmtime(), 341hcreate(), 342hdestroy(), 343hsearch(), 344inet_ntoa(), 345l64a(), 346lgamma(), 347lgammaf(), 348lgammal(), 349localeconv(), 350localtime(), 351lrand48(), 352mrand48(), 353nftw(), 354nl_langinfo(), 355putc_unlocked(), 356putchar_unlocked(), 357putenv(), 358rand(), 359readdir(), 360setenv(), 361setgrent(), 362setkey(), 363setpwent(), 364strerror(), 365strsignal(), 366strtok(), 367ttyname(), 368unsetenv(), 369wcstombs(), 370wctomb() 371.Ed 372.Pp 373The 374.Fn ctermid 375and 376.Fn tmpnam 377functions are not thread-safe when passed a 378.Dv NULL 379argument. 380The 381.Fn wcrtomb , 382.Fn wcsrtombs , 383and 384.Fn wcsnrtombs 385functions are not thread-safe when passed a 386.Dv NULL 387.Fa ps 388argument. 389.Sh ENVIRONMENT 390.Bl -tag -width "RTHREAD_DEBUG" 391.It Ev RTHREAD_DEBUG 392Enables debugging output when set to a positive number, 393with larger numbers generating more verbose output. 394.El 395.Sh SEE ALSO 396.Xr intro 3 , 397.Xr pthread_atfork 3 , 398.Xr pthread_attr_init 3 , 399.Xr pthread_attr_setdetachstate 3 , 400.Xr pthread_attr_setguardsize 3 , 401.Xr pthread_attr_setstack 3 , 402.Xr pthread_attr_setstackaddr 3 , 403.Xr pthread_attr_setstacksize 3 , 404.Xr pthread_barrier_init 3 , 405.Xr pthread_barrier_wait 3 , 406.Xr pthread_barrierattr_getpshared 3 , 407.Xr pthread_barrierattr_init 3 , 408.Xr pthread_cancel 3 , 409.Xr pthread_cleanup_pop 3 , 410.Xr pthread_cleanup_push 3 , 411.Xr pthread_cond_broadcast 3 , 412.Xr pthread_cond_destroy 3 , 413.Xr pthread_cond_init 3 , 414.Xr pthread_cond_signal 3 , 415.Xr pthread_cond_timedwait 3 , 416.Xr pthread_cond_wait 3 , 417.Xr pthread_condattr_init 3 , 418.Xr pthread_create 3 , 419.Xr pthread_detach 3 , 420.Xr pthread_equal 3 , 421.Xr pthread_exit 3 , 422.Xr pthread_getspecific 3 , 423.Xr pthread_join 3 , 424.Xr pthread_key_create 3 , 425.Xr pthread_key_delete 3 , 426.Xr pthread_kill 3 , 427.Xr pthread_main_np 3 , 428.Xr pthread_mutex_destroy 3 , 429.Xr pthread_mutex_init 3 , 430.Xr pthread_mutex_lock 3 , 431.Xr pthread_mutex_unlock 3 , 432.Xr pthread_mutexattr 3 , 433.Xr pthread_once 3 , 434.Xr pthread_rwlock_destroy 3 , 435.Xr pthread_rwlock_init 3 , 436.Xr pthread_rwlock_rdlock 3 , 437.Xr pthread_rwlock_unlock 3 , 438.Xr pthread_rwlock_wrlock 3 , 439.Xr pthread_rwlockattr_destroy 3 , 440.Xr pthread_rwlockattr_getpshared 3 , 441.Xr pthread_rwlockattr_init 3 , 442.Xr pthread_rwlockattr_setpshared 3 , 443.Xr pthread_schedparam 3 , 444.Xr pthread_self 3 , 445.Xr pthread_set_name_np 3 , 446.Xr pthread_setspecific 3 , 447.Xr pthread_sigmask 3 , 448.Xr pthread_spin_init 3 , 449.Xr pthread_spin_lock 3 , 450.Xr pthread_spin_unlock 3 , 451.Xr pthread_stackseg_np 3 , 452.Xr pthread_testcancel 3 , 453.Xr pthread_yield 3 454.Sh STANDARDS 455The thread library provides functions that 456conform to 457.St -p1003.1-96 458and various later versions of 459.Pq Dq Tn POSIX . 460Please consult the manpages for the individual functions for details. 461.Sh HISTORY 462This 1-to-1 implementation of the 463.Nm 464API initially appeared in 465.Ox 3.9 466under the name 467.Dq librthread 468as an alternative to the pure-userspace (N-to-1) implementation. 469In 470.Ox 5.2 471it became the default implementation and was renamed to 472.Dq libpthread . 473.Sh AUTHORS 474.An -nosplit 475.An Ted Unangst Aq tedu@openbsd.org , 476.An Kurt Miller Aq kurt@openbsd.org , 477.An Marco S Hyman Aq marc@openbsd.org , 478.An Otto Moerbeek Aq otto@openbsd.org , 479and 480.An Philip Guenther Aq guenther@openbsd.org . 481