1.\" $OpenBSD: pthreads.3,v 1.44 2022/02/06 00:29:02 jsg Exp $ 2.\" David Leonard <d@openbsd.org>, 1998. Public domain. 3.Dd $Mdocdate: February 6 2022 $ 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_get_name_np 173Get the name of a thread. 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 Per-Thread Context Routines 180The functions available are as follows: 181.Pp 182.Bl -tag -width "pthread_getspecific()" -compact 183.It Fn pthread_key_create 184Thread-specific data key creation. 185.It Fn pthread_key_delete 186Delete a thread-specific data key. 187.It Fn pthread_getspecific 188Get a thread-specific data value. 189.It Fn pthread_setspecific 190Set a thread-specific data value. 191.El 192.Ss Read/Write Lock Routines 193The functions available are as follows: 194.Pp 195.Bl -tag -width "pthread_rwlockattr_getpshared()" -compact 196.It Fn pthread_rwlock_init 197Initialise a read/write lock. 198.It Fn pthread_rwlock_destroy 199Destroy a read/write lock. 200.It Fn pthread_rwlock_rdlock 201Acquire a read/write lock for reading. 202.It Fn pthread_rwlock_timedrdlock 203Attempt to acquire a read/write lock for reading before a specific 204point in time. 205.It Fn pthread_rwlock_tryrdlock 206Attempt to acquire a read/write lock for reading without blocking. 207.It Fn pthread_rwlock_wrlock 208Acquire a read/write lock for writing. 209.It Fn pthread_rwlock_timedwrlock 210Attempt to acquire a read/write lock for writing before a specific 211point in time. 212.It Fn pthread_rwlock_trywrlock 213Attempt to acquire a read/write lock for writing without blocking. 214.It Fn pthread_rwlock_unlock 215Release a read/write lock. 216.It Fn pthread_rwlockattr_init 217Initialise a read/write lock. 218.It Fn pthread_rwlockattr_destroy 219Destroy a read/write lock. 220.It Fn pthread_rwlockattr_getpshared 221Get the process shared attribute. 222.It Fn pthread_rwlockattr_setpshared 223Set the process shared attribute. 224.El 225.Ss Spinlock Routines 226The functions available are as follows: 227.Pp 228.Bl -tag -width "pthread_spin_trylock()" -compact 229.It Fn pthread_spin_init 230Initialize a spinlock object. 231.It Fn pthread_spin_destroy 232Destroy a spinlock object. 233.It Fn pthread_spin_lock 234Lock a spinlock object. 235.It Fn pthread_spin_trylock 236Attempt to lock a spinlock without blocking. 237.It Fn pthread_spin_unlock 238Unlock a spinlock object. 239.El 240.Ss Thread Routines 241The functions available are as follows: 242.Pp 243.Bl -tag -width "pthread_getconcurrency()" -compact 244.It Fn pthread_create 245Create a new thread. 246.It Fn pthread_cancel 247Cancel execution of a thread. 248.It Fn pthread_detach 249Detach a thread. 250.It Fn pthread_equal 251Compare thread IDs. 252.It Fn pthread_exit 253Terminate the calling thread. 254.It Fn pthread_getconcurrency 255Get level of concurrency. 256.It Fn pthread_setconcurrency 257Set level of concurrency. 258.It Fn pthread_join 259Wait for thread termination. 260.It Fn pthread_kill 261Send a signal to a specific thread. 262.It Fn pthread_once 263Dynamic package initialisation. 264.It Fn pthread_self 265Get the calling thread's ID. 266.It Fn pthread_setcancelstate 267Set cancelability state. 268.It Fn pthread_setcanceltype 269Set cancelability state. 270.It Fn pthread_testcancel 271Set cancelability state. 272.It Fn pthread_sigmask 273Examine/change a thread's signal mask. 274.It Fn pthread_getcpuclockid 275Get a CPU time clock for a thread. 276.El 277.Ss Thread stacks 278Each thread has a different stack, whether it be provided by a 279user attribute, or provided automatically by the system. 280If a thread overflows its stack, unpredictable results may occur. 281System-allocated stacks (including that of the initial thread) 282are typically allocated in such a way that a 283.Dv SIGSEGV 284signal is delivered to the process when a stack overflows. 285.Pp 286Signals handlers are normally run on the stack of the currently executing 287thread. 288Hence, if you want to handle the 289.Dv SIGSEGV 290signal from stack overflow for a thread, you should use 291.Xr sigaltstack 2 292in that thread. 293.Ss Thread safety 294The following functions are not thread-safe: 295.Bd -filled 296asctime(), 297basename(), 298catgets(), 299crypt(), 300ctime(), 301dbm_clearerr(), 302dbm_close(), 303dbm_delete(), 304dbm_error(), 305dbm_fetch(), 306dbm_firstkey(), 307dbm_nextkey(), 308dbm_open(), 309dbm_store(), 310dirname(), 311dlerror(), 312drand48(), 313ecvt(), 314encrypt(), 315endgrent(), 316endpwent(), 317fcvt(), 318ftw(), 319gcvt(), 320getc_unlocked(), 321getchar_unlocked(), 322.\" getdate(), 323getenv(), 324getgrent(), 325getgrgid(), 326getgrnam(), 327gethostbyaddr(), 328gethostbyname(), 329gethostent(), 330getlogin(), 331getnetbyaddr(), 332getnetbyname(), 333getnetent(), 334getopt(), 335getprotobyname(), 336getprotobynumber(), 337getprotoent(), 338getpwent(), 339getpwnam(), 340getpwuid(), 341getservbyname(), 342getservbyport(), 343getservent(), 344gmtime(), 345hcreate(), 346hdestroy(), 347hsearch(), 348inet_ntoa(), 349l64a(), 350lgamma(), 351lgammaf(), 352lgammal(), 353localeconv(), 354localtime(), 355lrand48(), 356mrand48(), 357nftw(), 358nl_langinfo(), 359putc_unlocked(), 360putchar_unlocked(), 361putenv(), 362rand(), 363readdir(), 364setenv(), 365setgrent(), 366setkey(), 367setpwent(), 368strerror(), 369strsignal(), 370strtok(), 371ttyname(), 372unsetenv(), 373wcstombs(), 374wctomb() 375.Ed 376.Pp 377The 378.Fn ctermid 379and 380.Fn tmpnam 381functions are not thread-safe when passed a 382.Dv NULL 383argument. 384The 385.Fn wcrtomb , 386.Fn wcsrtombs , 387and 388.Fn wcsnrtombs 389functions are not thread-safe when passed a 390.Dv NULL 391.Fa ps 392argument. 393.Sh ENVIRONMENT 394.Bl -tag -width "RTHREAD_DEBUG" 395.It Ev RTHREAD_DEBUG 396Enables debugging output when set to a positive number, 397with larger numbers generating more verbose output. 398.El 399.Sh SEE ALSO 400.Xr intro 3 , 401.Xr pthread_atfork 3 , 402.Xr pthread_attr_init 3 , 403.Xr pthread_attr_setdetachstate 3 , 404.Xr pthread_attr_setguardsize 3 , 405.Xr pthread_attr_setstack 3 , 406.Xr pthread_attr_setstackaddr 3 , 407.Xr pthread_attr_setstacksize 3 , 408.Xr pthread_barrier_init 3 , 409.Xr pthread_barrier_wait 3 , 410.Xr pthread_barrierattr_getpshared 3 , 411.Xr pthread_barrierattr_init 3 , 412.Xr pthread_cancel 3 , 413.Xr pthread_cleanup_pop 3 , 414.Xr pthread_cleanup_push 3 , 415.Xr pthread_cond_broadcast 3 , 416.Xr pthread_cond_destroy 3 , 417.Xr pthread_cond_init 3 , 418.Xr pthread_cond_signal 3 , 419.Xr pthread_cond_timedwait 3 , 420.Xr pthread_cond_wait 3 , 421.Xr pthread_condattr_init 3 , 422.Xr pthread_create 3 , 423.Xr pthread_detach 3 , 424.Xr pthread_equal 3 , 425.Xr pthread_exit 3 , 426.Xr pthread_get_name_np 3 , 427.Xr pthread_getcpuclockid 3 , 428.Xr pthread_getspecific 3 , 429.Xr pthread_join 3 , 430.Xr pthread_key_create 3 , 431.Xr pthread_key_delete 3 , 432.Xr pthread_kill 3 , 433.Xr pthread_main_np 3 , 434.Xr pthread_mutex_destroy 3 , 435.Xr pthread_mutex_init 3 , 436.Xr pthread_mutex_lock 3 , 437.Xr pthread_mutex_unlock 3 , 438.Xr pthread_mutexattr 3 , 439.Xr pthread_once 3 , 440.Xr pthread_rwlock_destroy 3 , 441.Xr pthread_rwlock_init 3 , 442.Xr pthread_rwlock_rdlock 3 , 443.Xr pthread_rwlock_unlock 3 , 444.Xr pthread_rwlock_wrlock 3 , 445.Xr pthread_rwlockattr_destroy 3 , 446.Xr pthread_rwlockattr_getpshared 3 , 447.Xr pthread_rwlockattr_init 3 , 448.Xr pthread_rwlockattr_setpshared 3 , 449.Xr pthread_schedparam 3 , 450.Xr pthread_self 3 , 451.Xr pthread_set_name_np 3 , 452.Xr pthread_setspecific 3 , 453.Xr pthread_sigmask 3 , 454.Xr pthread_spin_init 3 , 455.Xr pthread_spin_lock 3 , 456.Xr pthread_spin_unlock 3 , 457.Xr pthread_stackseg_np 3 , 458.Xr pthread_testcancel 3 , 459.Xr pthread_yield 3 460.Sh STANDARDS 461The thread library provides functions that 462conform to 463.St -p1003.1-96 464and various later versions of 465.Pq Dq Tn POSIX . 466Consult the manpages for the individual functions for details. 467.Sh HISTORY 468This 1-to-1 implementation of the 469.Nm 470API initially appeared in 471.Ox 3.9 472under the name 473.Dq librthread 474as an alternative to the pure-userspace (N-to-1) implementation. 475In 476.Ox 5.2 477it became the default implementation and was renamed to 478.Dq libpthread . 479.Sh AUTHORS 480.An -nosplit 481.An Ted Unangst Aq Mt tedu@openbsd.org , 482.An Kurt Miller Aq Mt kurt@openbsd.org , 483.An Marco S Hyman Aq Mt marc@openbsd.org , 484.An Otto Moerbeek Aq Mt otto@openbsd.org , 485and 486.An Philip Guenther Aq Mt guenther@openbsd.org . 487