PTHREADS(3) | Library Functions Manual | PTHREADS(3)

# NAME

`pthreads` — POSIX 1003.1c thread interface

# DESCRIPTION

A thread is a flow of control within a process. Each thread represents a minimal amount of state: normally just the CPU state and a signal mask. All other process state (such as memory, file descriptors) is shared among all of the threads in the process.

In OpenBSD, threads use a 1-to-1 implementation, where every thread is independently scheduled by the kernel.

For the purpose of this document, the functions available are grouped in the following categories. For further information, see the individual man page for each function.

- Attribute Object Routines
- Barrier Routines
- Cleanup Routines
- Condition Variable Routines
- Mutex Routines
- Non Portable Extensions
- Per-Thread Context Routines
- Read/Write Lock Routines
- Spinlock Routines
- Thread Routines

## Attribute Object Routines

The functions available are as follows:

`pthread_attr_init`()
  Initialise a threads attribute object.
`pthread_attr_destroy`()
  Destroy a threads attribute object.
`pthread_attr_getdetachstate`()
  Get detachstate attribute.
`pthread_attr_setdetachstate`()
  Set detachstate attribute.
`pthread_attr_getstack`()
  Get stackaddr and stacksize attributes.
`pthread_attr_setstack`()
  Set stackaddr and stacksize attributes.
`pthread_attr_getstackaddr`()
  Get stackaddr attribute.
`pthread_attr_setstackaddr`()
  Set stackaddr attribute.
`pthread_attr_getstacksize`()
  Get stacksize attribute.
`pthread_attr_setstacksize`()
  Set stacksize attribute.
`pthread_attr_getguardsize`()
  Get guardsize attribute.
`pthread_attr_setguardsize`()
  Set guardsize attribute.

## Barrier Routines

The functions available are as follows:

`pthread_barrier_init`()
  Initialize a barrier object.
`pthread_barrier_destroy`()
  Destroy a barrier object.
`pthread_barrier_wait`()
  Synchronize at a barrier.
`pthread_barrierattr_init`()
  Initialize a barrier's attribute object.
`pthread_barrierattr_destroy`()
  Destroy a barrier's attribute object.
`pthread_barrierattr_getpshared`()
  Get the process-shared attribute of the barrier attribute's object.
`pthread_barrierattr_setpshared`()
  Set the process-shared attribute of the barrier attribute's object.

## Cleanup Routines

The functions available are as follows:

`pthread_atfork`()
  Register fork handlers.
`pthread_cleanup_pop`()
  Call the first cleanup routine.
`pthread_cleanup_push`()
  Add a cleanup function for thread exit.

## Condition Variable Routines

The functions available are as follows:

`pthread_cond_init`()
  Create a condition variable.
`pthread_cond_destroy`()
  Destroy a condition variable.
`pthread_cond_broadcast`()
  Unblock all threads waiting for a condition variable.
`pthread_cond_signal`()
  Unblock a thread waiting for a condition variable.
`pthread_cond_timedwait`()
  Wait on a condition variable until a specific point in time.
`pthread_cond_wait`()
  Wait on a condition variable.
`pthread_condattr_init`()
  Initialise a condition variable attribute object.
`pthread_condattr_destroy`()
  Destroy a condition variable attribute object.
`pthread_condattr_getclock`()
  Get clock attribute.
`pthread_condattr_setclock`()
  Set clock attribute.

## Mutex Routines

The functions available are as follows:

`pthread_mutex_init`()
  Create a mutex.
`pthread_mutex_destroy`()
  Free resources allocated for a mutex.
`pthread_mutex_lock`()
  Lock a mutex.
`pthread_mutex_timedlock`()
  Attempt to lock a mutex before a specific point in time.
`pthread_mutex_trylock`()
  Attempt to lock a mutex without blocking.
`pthread_mutex_unlock`()
  Unlock a mutex.
`pthread_mutexattr_init`()
  Mutex attribute operations.
`pthread_mutexattr_destroy`()
  Mutex attribute operations.
`pthread_mutexattr_getprioceiling`()
  Mutex attribute operations.
`pthread_mutexattr_setprioceiling`()
  Mutex attribute operations.
`pthread_mutexattr_getprotocol`()
  Mutex attribute operations.
`pthread_mutexattr_setprotocol`()
  Mutex attribute operations.
`pthread_mutexattr_gettype`()
  Mutex attribute operations.
`pthread_mutexattr_settype`()
  Mutex attribute operations.

## Non Portable Extensions

The functions available are as follows:

`pthread_main_np`()
  Identify the main thread.
`pthread_set_name_np`()
  Set the name of a thread.
`pthread_get_name_np`()
  Get the name of a thread.
`pthread_stackseg_np`()
  Return stack size and location.
`pthread_yield`()
  Yield control of the current thread.

## Per-Thread Context Routines

The functions available are as follows:

`pthread_key_create`()
  Thread-specific data key creation.
`pthread_key_delete`()
  Delete a thread-specific data key.
`pthread_getspecific`()
  Get a thread-specific data value.
`pthread_setspecific`()
  Set a thread-specific data value.

## Read/Write Lock Routines

The functions available are as follows:

`pthread_rwlock_init`()
  Initialise a read/write lock.
`pthread_rwlock_destroy`()
  Destroy a read/write lock.
`pthread_rwlock_rdlock`()
  Acquire a read/write lock for reading.
`pthread_rwlock_timedrdlock`()
  Attempt to acquire a read/write lock for reading before a specific point in time.
`pthread_rwlock_tryrdlock`()
  Attempt to acquire a read/write lock for reading without blocking.
`pthread_rwlock_wrlock`()
  Acquire a read/write lock for writing.
`pthread_rwlock_timedwrlock`()
  Attempt to acquire a read/write lock for writing before a specific point in time.
`pthread_rwlock_trywrlock`()
  Attempt to acquire a read/write lock for writing without blocking.
`pthread_rwlock_unlock`()
  Release a read/write lock.
`pthread_rwlockattr_init`()
  Initialise a read/write lock attributes object.
`pthread_rwlockattr_destroy`()
  Destroy a read/write lock attributes object.
`pthread_rwlockattr_getpshared`()
  Get the process shared attribute.
`pthread_rwlockattr_setpshared`()
  Set the process shared attribute.

## Spinlock Routines

The functions available are as follows:

`pthread_spin_init`()
  Initialize a spinlock object.
`pthread_spin_destroy`()
  Destroy a spinlock object.
`pthread_spin_lock`()
  Lock a spinlock object.
`pthread_spin_trylock`()
  Attempt to lock a spinlock without blocking.
`pthread_spin_unlock`()
  Unlock a spinlock object.

## Thread Routines

The functions available are as follows:

`pthread_create`()
  Create a new thread.
`pthread_cancel`()
  Cancel execution of a thread.
`pthread_detach`()
  Detach a thread.
`pthread_equal`()
  Compare thread IDs.
`pthread_exit`()
  Terminate the calling thread.
`pthread_getconcurrency`()
  Get level of concurrency.
`pthread_setconcurrency`()
  Set level of concurrency.
`pthread_join`()
  Wait for thread termination.
`pthread_kill`()
  Send a signal to a specific thread.
`pthread_once`()
  Dynamic package initialisation.
`pthread_self`()
  Get the calling thread's ID.
`pthread_setcancelstate`()
  Set cancelability state.
`pthread_setcanceltype`()
  Set cancelability state.
`pthread_testcancel`()
  Set cancelability state.
`pthread_sigmask`()
  Examine/change a thread's signal mask.
`pthread_getcpuclockid`()
  Get a CPU time clock for a thread.

## Thread stacks

Each thread has a different stack, whether it be provided by a user attribute, or provided automatically by the system. If a thread overflows its stack, unpredictable results may occur. System-allocated stacks (including that of the initial thread) are typically allocated in such a way that a `SIGSEGV` signal is delivered to the process when a stack overflows.

Signals handlers are normally run on the stack of the currently executing thread. Hence, if you want to handle the `SIGSEGV` signal from stack overflow for a thread, you should use sigaltstack(2) in that thread.

## Thread safety

The following functions are not thread-safe:

asctime(), basename(), catgets(), crypt(), ctime(), dbm_clearerr(), dbm_close(), dbm_delete(), dbm_error(), dbm_fetch(), dbm_firstkey(), dbm_nextkey(), dbm_open(), dbm_store(), dirname(), dlerror(), drand48(), ecvt(), encrypt(), endgrent(), endpwent(), fcvt(), ftw(), gcvt(), getc_unlocked(), getchar_unlocked(), getenv(), getgrent(), getgrgid(), getgrnam(), gethostbyaddr(), gethostbyname(), gethostent(), getlogin(), getnetbyaddr(), getnetbyname(), getnetent(), getopt(), getprotobyname(), getprotobynumber(), getprotoent(), getpwent(), getpwnam(), getpwuid(), getservbyname(), getservbyport(), getservent(), gmtime(), hcreate(), hdestroy(), hsearch(), inet_ntoa(), l64a(), lgamma(), lgammaf(), lgammal(), localeconv(), localtime(), lrand48(), mrand48(), nftw(), nl_langinfo(), putc_unlocked(), putchar_unlocked(), putenv(), rand(), readdir(), setenv(), setgrent(), setkey(), setpwent(), strerror(), strsignal(), strtok(), ttyname(), unsetenv(), wcstombs(), wctomb()

The `ctermid`() and `tmpnam`() functions are not thread-safe when passed a `NULL` argument. The `wcrtomb`(), `wcsrtombs`(), and `wcsnrtombs`() functions are not thread-safe when passed a `NULL` ps argument.

# ENVIRONMENT

`RTHREAD_DEBUG`
  Enables debugging output when set to a positive number, with larger numbers generating more verbose output.

# SEE ALSO

intro(3), pthread_atfork(3), pthread_attr_init(3), pthread_attr_setdetachstate(3), pthread_attr_setguardsize(3), pthread_attr_setstack(3), pthread_attr_setstackaddr(3), pthread_attr_setstacksize(3), pthread_barrier_init(3), pthread_barrier_wait(3), pthread_barrierattr_getpshared(3), pthread_barrierattr_init(3), pthread_cancel(3), pthread_cleanup_pop(3), pthread_cleanup_push(3), pthread_cond_init(3), pthread_condattr_init(3), pthread_create(3), pthread_detach(3), pthread_equal(3), pthread_exit(3), pthread_get_name_np(3), pthread_getcpuclockid(3), pthread_getspecific(3), pthread_join(3), pthread_key_create(3), pthread_key_delete(3), pthread_kill(3), pthread_main_np(3), pthread_mutex_destroy(3), pthread_mutex_init(3), pthread_mutex_lock(3), pthread_mutex_unlock(3), pthread_mutexattr(3), pthread_once(3), pthread_rwlock_destroy(3), pthread_rwlock_init(3), pthread_rwlock_rdlock(3), pthread_rwlock_unlock(3), pthread_rwlock_wrlock(3), pthread_rwlockattr_destroy(3), pthread_rwlockattr_getpshared(3), pthread_rwlockattr_init(3), pthread_rwlockattr_setpshared(3), pthread_schedparam(3), pthread_self(3), pthread_set_name_np(3), pthread_setspecific(3), pthread_sigmask(3), pthread_spin_init(3), pthread_spin_lock(3), pthread_spin_unlock(3), pthread_stackseg_np(3), pthread_testcancel(3), pthread_yield(3)

# STANDARDS

The thread library provides functions that conform to ISO/IEC 9945-1:1996 (“POSIX.1”) and various later versions of (“POSIX”). Consult the manpages for the individual functions for details.

# HISTORY

This 1-to-1 implementation of the `pthreads` API initially appeared in OpenBSD 3.9 under the name “librthread” as an alternative to the pure-userspace (N-to-1) implementation. In OpenBSD 5.2 it became the default implementation and was renamed to “libpthread”.

# AUTHORS

Ted Unangst <tedu@openbsd.org>, Kurt Miller <kurt@openbsd.org>, Marco S Hyman <marc@openbsd.org>, Otto Moerbeek <otto@openbsd.org>, and Philip Guenther <guenther@openbsd.org>.

July 3, 2025 | Debian