1.\" $OpenBSD: pthreads.3,v 1.41 2013/07/16 15:21:11 schwarze Exp $ 2.\" David Leonard <d@openbsd.org>, 1998. Public domain. 3.Dd $Mdocdate: July 16 2013 $ 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.It Fn pthread_getcpuclockid 273Get a CPU time clock for a thread. 274.El 275.Ss Thread stacks 276Each thread has a different stack, whether it be provided by a 277user attribute, or provided automatically by the system. 278If a thread overflows its stack, unpredictable results may occur. 279System-allocated stacks (including that of the initial thread) 280are typically allocated in such a way that a 281.Dv SIGSEGV 282signal is delivered to the process when a stack overflows. 283.Pp 284Signals handlers are normally run on the stack of the currently executing 285thread. 286Hence, if you want to handle the 287.Dv SIGSEGV 288signal from stack overflow for a thread, you should use 289.Xr sigaltstack 2 290in that thread. 291.Ss Thread safety 292The following functions are not thread-safe: 293.Bd -filled 294asctime(), 295basename(), 296catgets(), 297crypt(), 298ctime(), 299dbm_clearerr(), 300dbm_close(), 301dbm_delete(), 302dbm_error(), 303dbm_fetch(), 304dbm_firstkey(), 305dbm_nextkey(), 306dbm_open(), 307dbm_store(), 308dirname(), 309dlerror(), 310drand48(), 311ecvt(), 312encrypt(), 313endgrent(), 314endpwent(), 315fcvt(), 316ftw(), 317gcvt(), 318getc_unlocked(), 319getchar_unlocked(), 320.\" getdate(), 321getenv(), 322getgrent(), 323getgrgid(), 324getgrnam(), 325gethostbyaddr(), 326gethostbyname(), 327gethostent(), 328getlogin(), 329getnetbyaddr(), 330getnetbyname(), 331getnetent(), 332getopt(), 333getprotobyname(), 334getprotobynumber(), 335getprotoent(), 336getpwent(), 337getpwnam(), 338getpwuid(), 339getservbyname(), 340getservbyport(), 341getservent(), 342gmtime(), 343hcreate(), 344hdestroy(), 345hsearch(), 346inet_ntoa(), 347l64a(), 348lgamma(), 349lgammaf(), 350lgammal(), 351localeconv(), 352localtime(), 353lrand48(), 354mrand48(), 355nftw(), 356nl_langinfo(), 357putc_unlocked(), 358putchar_unlocked(), 359putenv(), 360rand(), 361readdir(), 362setenv(), 363setgrent(), 364setkey(), 365setpwent(), 366strerror(), 367strsignal(), 368strtok(), 369ttyname(), 370unsetenv(), 371wcstombs(), 372wctomb() 373.Ed 374.Pp 375The 376.Fn ctermid 377and 378.Fn tmpnam 379functions are not thread-safe when passed a 380.Dv NULL 381argument. 382The 383.Fn wcrtomb , 384.Fn wcsrtombs , 385and 386.Fn wcsnrtombs 387functions are not thread-safe when passed a 388.Dv NULL 389.Fa ps 390argument. 391.Sh ENVIRONMENT 392.Bl -tag -width "RTHREAD_DEBUG" 393.It Ev RTHREAD_DEBUG 394Enables debugging output when set to a positive number, 395with larger numbers generating more verbose output. 396.El 397.Sh SEE ALSO 398.Xr intro 3 , 399.Xr pthread_atfork 3 , 400.Xr pthread_attr_init 3 , 401.Xr pthread_attr_setdetachstate 3 , 402.Xr pthread_attr_setguardsize 3 , 403.Xr pthread_attr_setstack 3 , 404.Xr pthread_attr_setstackaddr 3 , 405.Xr pthread_attr_setstacksize 3 , 406.Xr pthread_barrier_init 3 , 407.Xr pthread_barrier_wait 3 , 408.Xr pthread_barrierattr_getpshared 3 , 409.Xr pthread_barrierattr_init 3 , 410.Xr pthread_cancel 3 , 411.Xr pthread_cleanup_pop 3 , 412.Xr pthread_cleanup_push 3 , 413.Xr pthread_cond_broadcast 3 , 414.Xr pthread_cond_destroy 3 , 415.Xr pthread_cond_init 3 , 416.Xr pthread_cond_signal 3 , 417.Xr pthread_cond_timedwait 3 , 418.Xr pthread_cond_wait 3 , 419.Xr pthread_condattr_init 3 , 420.Xr pthread_create 3 , 421.Xr pthread_detach 3 , 422.Xr pthread_equal 3 , 423.Xr pthread_exit 3 , 424.Xr pthread_getcpuclockid 3 , 425.Xr pthread_getspecific 3 , 426.Xr pthread_join 3 , 427.Xr pthread_key_create 3 , 428.Xr pthread_key_delete 3 , 429.Xr pthread_kill 3 , 430.Xr pthread_main_np 3 , 431.Xr pthread_mutex_destroy 3 , 432.Xr pthread_mutex_init 3 , 433.Xr pthread_mutex_lock 3 , 434.Xr pthread_mutex_unlock 3 , 435.Xr pthread_mutexattr 3 , 436.Xr pthread_once 3 , 437.Xr pthread_rwlock_destroy 3 , 438.Xr pthread_rwlock_init 3 , 439.Xr pthread_rwlock_rdlock 3 , 440.Xr pthread_rwlock_unlock 3 , 441.Xr pthread_rwlock_wrlock 3 , 442.Xr pthread_rwlockattr_destroy 3 , 443.Xr pthread_rwlockattr_getpshared 3 , 444.Xr pthread_rwlockattr_init 3 , 445.Xr pthread_rwlockattr_setpshared 3 , 446.Xr pthread_schedparam 3 , 447.Xr pthread_self 3 , 448.Xr pthread_set_name_np 3 , 449.Xr pthread_setspecific 3 , 450.Xr pthread_sigmask 3 , 451.Xr pthread_spin_init 3 , 452.Xr pthread_spin_lock 3 , 453.Xr pthread_spin_unlock 3 , 454.Xr pthread_stackseg_np 3 , 455.Xr pthread_testcancel 3 , 456.Xr pthread_yield 3 457.Sh STANDARDS 458The thread library provides functions that 459conform to 460.St -p1003.1-96 461and various later versions of 462.Pq Dq Tn POSIX . 463Please consult the manpages for the individual functions for details. 464.Sh HISTORY 465This 1-to-1 implementation of the 466.Nm 467API initially appeared in 468.Ox 3.9 469under the name 470.Dq librthread 471as an alternative to the pure-userspace (N-to-1) implementation. 472In 473.Ox 5.2 474it became the default implementation and was renamed to 475.Dq libpthread . 476.Sh AUTHORS 477.An -nosplit 478.An Ted Unangst Aq Mt tedu@openbsd.org , 479.An Kurt Miller Aq Mt kurt@openbsd.org , 480.An Marco S Hyman Aq Mt marc@openbsd.org , 481.An Otto Moerbeek Aq Mt otto@openbsd.org , 482and 483.An Philip Guenther Aq Mt guenther@openbsd.org . 484