PTHREADS(3) FreeBSD 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.
pthread_rwlockattr_destroy() Destroy a read/write lock.
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_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)
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 <
[email protected]>, Kurt Miller <
[email protected]>, Marco S
Hyman <
[email protected]>, Otto Moerbeek <
[email protected]>, and Philip
Guenther <
[email protected]>.
FreeBSD 14.1-RELEASE-p8 February 6, 2022 FreeBSD 14.1-RELEASE-p8