OpenBSD manual page server

Manual Page Search Parameters

PTHREADS(3) Library Functions Manual PTHREADS(3)

pthreadsPOSIX 1003.1c thread interface

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.

The functions available are as follows:

()
Initialise a threads attribute object.
()
Destroy a threads attribute object.
()
Get detachstate attribute.
()
Set detachstate attribute.
()
Get stackaddr and stacksize attributes.
()
Set stackaddr and stacksize attributes.
()
Get stackaddr attribute.
()
Set stackaddr attribute.
()
Get stacksize attribute.
()
Set stacksize attribute.
()
Get guardsize attribute.
()
Set guardsize attribute.

The functions available are as follows:

()
Initialize a barrier object.
()
Destroy a barrier object.
()
Synchronize at a barrier.
()
Initialize a barrier's attribute object.
()
Destroy a barrier's attribute object.
()
Get the process-shared attribute of the barrier attribute's object.
()
Set the process-shared attribute of the barrier attribute's object.

The functions available are as follows:

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

The functions available are as follows:

()
Create a condition variable.
()
Destroy a condition variable.
()
Unblock all threads waiting for a condition variable.
()
Unblock a thread waiting for a condition variable.
()
Wait on a condition variable until a specific point in time.
()
Wait on a condition variable.
()
Initialise a condition variable attribute object.
()
Destroy a condition variable attribute object.
()
Get clock attribute.
()
Set clock attribute.

The functions available are as follows:

()
Create a mutex.
()
Free resources allocated for a mutex.
()
Lock a mutex.
()
Attempt to lock a mutex before a specific point in time.
()
Attempt to lock a mutex without blocking.
()
Unlock a mutex.
()
Mutex attribute operations.
()
Mutex attribute operations.
()
Mutex attribute operations.
()
Mutex attribute operations.
()
Mutex attribute operations.
()
Mutex attribute operations.
()
Mutex attribute operations.
()
Mutex attribute operations.

The functions available are as follows:

()
Identify the main thread.
()
Set the name of a thread.
()
Get the name of a thread.
()
Return stack size and location.
()
Yield control of the current thread.

The functions available are as follows:

()
Thread-specific data key creation.
()
Delete a thread-specific data key.
()
Get a thread-specific data value.
()
Set a thread-specific data value.

The functions available are as follows:

()
Initialise a read/write lock.
()
Destroy a read/write lock.
()
Acquire a read/write lock for reading.
()
Attempt to acquire a read/write lock for reading before a specific point in time.
()
Attempt to acquire a read/write lock for reading without blocking.
()
Acquire a read/write lock for writing.
()
Attempt to acquire a read/write lock for writing before a specific point in time.
()
Attempt to acquire a read/write lock for writing without blocking.
()
Release a read/write lock.
()
Initialise a read/write lock.
()
Destroy a read/write lock.
()
Get the process shared attribute.
()
Set the process shared attribute.

The functions available are as follows:

()
Initialize a spinlock object.
()
Destroy a spinlock object.
()
Lock a spinlock object.
()
Attempt to lock a spinlock without blocking.
()
Unlock a spinlock object.

The functions available are as follows:

()
Create a new thread.
()
Cancel execution of a thread.
()
Detach a thread.
()
Compare thread IDs.
()
Terminate the calling thread.
()
Get level of concurrency.
()
Set level of concurrency.
()
Wait for thread termination.
()
Send a signal to a specific thread.
()
Dynamic package initialisation.
()
Get the calling thread's ID.
()
Set cancelability state.
()
Set cancelability state.
()
Set cancelability state.
()
Examine/change a thread's signal mask.
()
Get a CPU time clock for a thread.

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.

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 () and () functions are not thread-safe when passed a NULL argument. The (), (), and () functions are not thread-safe when passed a NULL ps argument.

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

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_broadcast(3), pthread_cond_destroy(3), pthread_cond_init(3), pthread_cond_signal(3), pthread_cond_timedwait(3), pthread_cond_wait(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)

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.

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”.

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>.

February 6, 2022 OpenBSD-current