DragonFly On-Line Manual Pages
PTHREAD(3) DragonFly Library Functions Manual PTHREAD(3)
NAME
pthread - POSIX thread functions
LIBRARY
POSIX Threads Library (libpthread, -lpthread)
SYNOPSIS
#include <pthread.h>
DESCRIPTION
POSIX threads are a set of functions that support applications with
requirements for multiple flows of control, called threads, within a
process. Multithreading is used to improve the performance of a program.
The POSIX thread functions are summarized in this section in the
following groups:
* Thread Routines
* Attribute Object Routines
* Mutex Routines
* Condition Variable Routines
* Read/Write Lock Routines
* Spin Lock Routines
* Barrier Routines
* Per-Thread Context Routines
* Cleanup Routines
Thread Routines
int pthread_create(pthread_t * restrict thread,
const pthread_attr_t * restrict attr,
void *(*start_routine)(void *), void * restrict arg)
Creates a new thread of execution.
int pthread_cancel(pthread_t thread)
Cancels execution of a thread.
int pthread_detach(pthread_t thread)
Marks a thread for deletion.
int pthread_equal(pthread_t t1, pthread_t t2)
Compares two thread IDs.
void pthread_exit(void *value_ptr)
Terminates the calling thread.
int pthread_getconcurrency(void)
Get the current thread's level of concurrency.
int pthread_getcpuclockid(pthread_t thread, clockid_t *clock_id)
Access a specific thread's CPU-time clock.
int pthread_getschedparam(pthread_t thread, int * restrict policy, struct
sched_param * restrict param)
Get the scheduling parameters of a specific thread.
int pthread_join(pthread_t thread, void **value_ptr)
Causes the calling thread to wait for the termination of the
specified thread.
int pthread_kill(pthread_t thread, int sig)
Delivers a signal to a specified thread.
int pthread_once(pthread_once_t *once_control, void
(*init_routine)(void))
Calls an initialization routine once.
pthread_t pthread_self(void)
Returns the thread ID of the calling thread.
int pthread_setcancelstate(int state, int *oldstate)
Sets the current thread's cancelability state.
int pthread_setcanceltype(int type, int *oldtype)
Sets the current thread's cancelability type.
int pthread_setconcurrency(int new_level)
Set the current thread's level of concurrency.
int pthread_setschedparam(pthread_t thread, int policy, struct
sched_param *param)
Set the scheduling parameters for a specific thread.
void pthread_sigmask(int how, const sigset_t * restrict set, sigset_t *
restrict oset)
Examine and/or change the calling thread's signal mask.
void pthread_testcancel(void)
Creates a cancellation point in the calling thread.
void pthread_yield(void)
Allows the scheduler to run another thread instead of the current
one.
Attribute Object Routines
int pthread_attr_destroy(pthread_attr_t *attr)
Destroy a thread attributes object.
int pthread_attr_getguardsize(const pthread_attr_t * restrict attr,
size_t * restrict guardsize)
Get the guard size attribute from a thread attributes object.
int pthread_attr_getinheritsched(const pthread_attr_t * restrict attr,
int * restrict inheritsched)
Get the inherit scheduling attribute from a thread attributes
object.
int pthread_attr_getschedparam(const pthread_attr_t * restrict attr,
struct sched_param * restrict param)
Get the scheduling parameter attribute from a thread attributes
object.
int pthread_attr_getschedpolicy(const pthread_attr_t * restrict attr, int
* restrict policy)
Get the scheduling policy attribute from a thread attributes
object.
int pthread_attr_getscope(const pthread_attr_t * restrict attr, int *
restrict contentionscope)
Get the contention scope attribute from a thread attributes
object.
int pthread_attr_getstack(const pthread_attr_t * restrict attr, void **
restrict stackaddr, size_t * restrict stacksize)
Get the stack attributes from a thread attributes object.
int pthread_attr_getstacksize(const pthread_attr_t * restrict attr,
size_t * restrict stacksize)
Get the stack size attribute from a thread attributes object.
int pthread_attr_getstackaddr(const pthread_attr_t *attr, void
**stackaddr)
Get the stack address attribute from a thread attributes object.
int pthread_attr_getdetachstate(const pthread_attr_t *attr, int
*detachstate)
Get the detach state attribute from a thread attributes object.
int pthread_attr_init(pthread_attr_t *attr)
Initialize a thread attributes object with default values.
int pthread_attr_setguardsize(pthread_attr_t *attr, size_t guardsize)
Set the guard size attribute in a thread attributes object.
int pthread_attr_setinheritsched(pthread_attr_t *attr, int inheritsched)
Set the inherit scheduling attribute in a thread attributes
object.
int pthread_attr_setschedparam(pthread_attr_t * restrict attr,
const struct sched_param * restrict param)
Set the scheduling parameter attribute in a thread attributes
object.
int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy)
Set the scheduling policy attribute in a thread attributes
object.
int pthread_attr_setscope(pthread_attr_t *attr, int contentionscope)
Set the contention scope attribute in a thread attributes object.
int pthread_attr_setstack(pthread_attr_t *attr, void *stackaddr, size_t
stacksize)
Set the stack attributes in a thread attributes object.
int pthread_attr_setstacksize(pthread_attr_t *attr, size_t stacksize)
Set the stack size attribute in a thread attributes object.
int pthread_attr_setstackaddr(pthread_attr_t *attr, void *stackaddr)
Set the stack address attribute in a thread attributes object.
int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate)
Set the detach state in a thread attributes object.
Mutex Routines
int pthread_mutexattr_destroy(pthread_mutexattr_t *attr)
Destroy a mutex attributes object.
int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t * restrict
attr, int * restrict ceiling)
Obtain priority ceiling attribute of mutex attribute object.
int pthread_mutexattr_getprotocol(const pthread_mutexattr_t * restrict
attr, int * restrict protocol)
Obtain protocol attribute of mutex attribute object.
int pthread_mutexattr_getpshared(const pthread_mutexattr_t * restrict
attr, int * restrict pshared)
Get the process shared setting from a mutex attributes object.
int pthread_mutexattr_gettype(const pthread_mutexattr_t * restrict attr,
int * restrict type)
Obtain the mutex type attribute in the specified mutex attributes
object.
int pthread_mutexattr_init(pthread_mutexattr_t *attr)
Initialize a mutex attributes object with default values.
int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr, int
ceiling)
Set priority ceiling attribute of mutex attribute object.
int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr, int
protocol)
Set protocol attribute of mutex attribute object.
int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr, int pshared)
Set the process shared setting in a mutex attributes object.
int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type)
Set the mutex type attribute that is used when a mutex is
created.
int pthread_mutex_destroy(pthread_mutex_t *mutex)
Destroy a mutex.
int pthread_mutex_getprioceiling(const pthread_mutex_t * restrict mutex,
int * restrict ceiling)
Get the priority ceiling of a mutex.
int pthread_mutex_init(pthread_mutex_t * restrict mutex,
const pthread_mutexattr_t * restrict attr)
Initialize a mutex with specified attributes.
int pthread_mutex_lock(pthread_mutex_t *mutex)
Lock a mutex and block until it becomes available.
int pthread_mutex_setprioceiling(pthread_mutex_t * restrict mutex, int
ceiling, int * restrict old_ceiling)
Set the priority ceiling of a mutex.
int pthread_mutex_timedlock(pthread_mutex_t * restrict mutex,
const struct timespec * restrict abstime)
Lock a mutex and block until it becomes available or until the
timeout expires.
int pthread_mutex_trylock(pthread_mutex_t *mutex)
Try to lock a mutex, but do not block if the mutex is locked by
another thread, including the current thread.
int pthread_mutex_unlock(pthread_mutex_t *mutex)
Unlock a mutex.
Condition Variable Routines
int pthread_condattr_destroy(pthread_condattr_t *attr)
Destroy a condition variable attributes object.
int pthread_condattr_getclock(const pthread_condattr_t * restrict attr,
clockid_t * restrict clock_id)
Get the clock selection attribute from a condition variable
attributes object.
int pthread_condattr_init(pthread_condattr_t *attr)
Initialize a condition variable attributes object with default
values.
int pthread_condattr_getpshared(const pthread_condattr_t * restrict attr,
int * restrict pshared)
Get the process shared setting from a condition variable
attributes object.
int pthread_condattr_setclock(pthread_condattr_t *attr, clockid_t
clock_id)
Set the clock selection attribute in a condition variable
attributes object.
int pthread_condattr_setpshared(pthread_condattr_t *attr, int pshared)
Set the process shared setting in a condition variable attributes
object.
int pthread_cond_broadcast(pthread_cond_t *cond)
Unblock all threads currently blocked on the specified condition
variable.
int pthread_cond_destroy(pthread_cond_t *cond)
Destroy a condition variable.
int pthread_cond_init(pthread_cond_t * restrict cond, const
pthread_condattr_t * restrict attr)
Initialize a condition variable with specified attributes.
int pthread_cond_signal(pthread_cond_t *cond)
Unblock at least one of the threads blocked on the specified
condition variable.
int pthread_cond_timedwait(pthread_cond_t * restrict cond,
pthread_mutex_t * restrict mutex,
const struct timespec * restrict abstime)
Wait no longer than the specified time for a condition and lock
the specified mutex.
int pthread_cond_wait(pthread_cond_t * restrict cond, pthread_mutex_t *
restrict mutex)
Wait for a condition and lock the specified mutex.
Read/Write Lock Routines
int pthread_rwlock_destroy(pthread_rwlock_t *lock)
Destroy a read/write lock object.
int pthread_rwlock_init(pthread_rwlock_t * restrict lock,
const pthread_rwlockattr_t * restrict attr)
Initialize a read/write lock object.
int pthread_rwlock_rdlock(pthread_rwlock_t *lock)
Lock a read/write lock for reading, blocking until the lock can
be acquired.
int pthread_rwlock_timedrdlock(pthread_rwlock_t * restrict lock, const
struct timespec * restrict abstime)
Lock a read/write lock for reading with a timeout.
int pthread_rwlock_timedwrlock(pthread_rwlock_t * restrict lock, const
struct timespec * restrict abstime)
Lock a read/write lock for writing with a timeout.
int pthread_rwlock_tryrdlock(pthread_rwlock_t *lock)
Attempt to lock a read/write lock for reading, without blocking
if the lock is unavailable.
int pthread_rwlock_trywrlock(pthread_rwlock_t *lock)
Attempt to lock a read/write lock for writing, without blocking
if the lock is unavailable.
int pthread_rwlock_unlock(pthread_rwlock_t *lock)
Unlock a read/write lock.
int pthread_rwlock_wrlock(pthread_rwlock_t *lock)
Lock a read/write lock for writing, blocking until the lock can
be acquired.
int pthread_rwlockattr_destroy(pthread_rwlockattr_t *attr)
Destroy a read/write lock attribute object.
int
pthread_rwlockattr_getpshared(const pthread_rwlockattr_t *
restrict attr, int * restrict pshared)
Retrieve the process shared setting for the read/write lock
attribute object.
int pthread_rwlockattr_init(pthread_rwlockattr_t *attr)
Initialize a read/write lock attribute object.
int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *attr, int
pshared)
Set the process shared setting for the read/write lock attribute
object.
Spin Lock Routines
int pthread_spin_destroy(pthread_spinlock_t *lock)
Destroy a spin lock object.
int pthread_spin_init(pthread_spinlock_t *lock, int pshared)
Initialize a spin lock object.
int pthread_spin_lock(pthread_spinlock_t *lock)
Lock a spin lock object.
int pthread_spin_trylock(pthread_spinlock_t *lock)
Lock a spin lock object if it is not held.
int pthread_spin_unlock(pthread_spinlock_t *lock)
Unlock a spin lock object.
Barrier Routines
int pthread_barrier_destroy(pthread_barrier_t *barrier)
Delete a barrier and its resources.
int pthread_barrier_init(pthread_barrier_t * restrict barrier, const
pthread_barrierattr_t * restrict attr, unsigned count)
Initialize a barrier with the specified attribute object.
int pthread_barrier_wait(pthread_barrier_t *barrier)
Block the calling threads until the barrier count is reached.
int pthread_barrierattr_destroy(pthread_barrierattr_t *attr)
Destroy a barrier attribute object.
int pthread_barrierattr_getpshared(const pthread_barrierattr_t * restrict
attr, int * restrict pshared)
Get the process-shared attribute from a barrier attribute object.
int pthread_barrierattr_init(pthread_barrierattr_t *attr)
Initialize a barrier attribute object.
int pthread_barrierattr_setpshared(pthread_barrierattr_t *attr, int
pshared)
Set the process-shared attribute in a barrier attribute object.
Per-Thread Context Routines
int pthread_key_create(pthread_key_t *key, void (*routine)(void *))
Create a thread-specific data key.
int pthread_key_delete(pthread_key_t key)
Delete a thread-specific data key.
void * pthread_getspecific(pthread_key_t key)
Get the thread-specific value for the specified key.
int pthread_setspecific(pthread_key_t key, const void *value_ptr)
Set the thread-specific value for the specified key.
Cleanup Routines
int pthread_atfork(void (*prepare)(void), void (*parent)(void),
void (*child)(void))
Register fork handlers
void pthread_cleanup_pop(int execute)
Remove the routine at the top of the calling thread's
cancellation cleanup stack and optionally invoke it.
void pthread_cleanup_push(void (*routine)(void *), void *routine_arg)
Push the specified cancellation cleanup handler onto the calling
thread's cancellation stack.
IMPLEMENTATION NOTES
The current DragonFly POSIX thread implementation is built in the library
libthread_xu which contains both thread-safe libc functions and the
thread functions.
In DragonFly, it is possible to switch the threading library used by
dynamically linked binaries at execution time by re-linking
/usr/lib/libpthread.so.x to a different library in /usr/lib/thread. At
link time, ld(1) reads the SONAME of libpthread.so, which is set to
libpthread.so.0 (or a higher major, if there were ABI changes). For
normal libraries libfoo.so is usually a symlink to libfoo.so.3 which also
has its SONAME set to libfoo.so.3, so that if libfoo.so.4 is installed,
programs will still continue to use libfoo.so.3 and not follow the
symlink libfoo.so to the newer (and possibly incompatible) libfoo.so.4.
What we do for libpthread.so is approximately the opposite: libpthread.so
is not a symlink but nevertheless has its SONAME set to libpthread.so.0.
libpthread.so.0, however, is a symlink to the threading library of the
user's choice. The linker will use the default threading library which
libpthread.so is linked to, but the runtime linker will instead follow
the symlink.
libc.so defines all pthread functions as weak symbols except for
pthread_create() (which is defined by libpthread.so.x to satisfy ld(1)).
At execution time, rtld(1) will resolve all these references to the
strong symbols from the thread library.
A DragonFly specific option exists in gcc(1) to simplify the linking of
threaded processes. gcc -pthread links a threaded process against
libpthread.so instead of libc.
SEE ALSO
pthread_atfork(3), pthread_attr_destroy(3),
pthread_attr_getdetachstate(3), pthread_attr_getguardsize(3),
pthread_attr_getinheritsched(3), pthread_attr_getschedparam(3),
pthread_attr_getschedpolicy(3), pthread_attr_getscope(3),
pthread_attr_getstack(3), pthread_attr_getstackaddr(3),
pthread_attr_getstacksize(3), pthread_attr_init(3),
pthread_attr_setdetachstate(3), pthread_attr_setguardsize(3),
pthread_attr_setinheritsched(3), pthread_attr_setschedparam(3),
pthread_attr_setschedpolicy(3), pthread_attr_setscope(3),
pthread_attr_setstack(3), pthread_attr_setstackaddr(3),
pthread_attr_setstacksize(3), pthread_barrierattr_destroy(3),
pthread_barrierattr_getpshared(3), pthread_barrierattr_init(3),
pthread_barrierattr_setpshared(3), pthread_barrier_destroy(3),
pthread_barrier_init(3), pthread_barrier_wait(3), pthread_cancel(3),
pthread_cleanup_pop(3), pthread_cleanup_push(3),
pthread_condattr_destroy(3), pthread_condattr_getclock(3),
pthread_condattr_getpshared(3), pthread_condattr_init(3),
pthread_condattr_setclock(3), pthread_condattr_setpshared(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_create(3), pthread_detach(3), pthread_equal(3), pthread_exit(3),
pthread_getconcurrency(3), pthread_getcpuclockid(3),
pthread_getschedparam(3), pthread_getspecific(3), pthread_join(3),
pthread_key_create(3), pthread_key_delete(3), pthread_kill(3),
pthread_mutexattr_destroy(3), pthread_mutexattr_getprioceiling(3),
pthread_mutexattr_getprotocol(3), pthread_mutexattr_getpshared(3),
pthread_mutexattr_gettype(3), pthread_mutexattr_init(3),
pthread_mutexattr_setprioceiling(3), pthread_mutexattr_setprotocol(3),
pthread_mutexattr_setpshared(3), pthread_mutexattr_settype(3),
pthread_mutex_destroy(3), pthread_mutex_getprioceiling(3),
pthread_mutex_init(3), pthread_mutex_lock(3),
pthread_mutex_setprioceiling(3), pthread_mutex_timedlock(3),
pthread_mutex_trylock(3), pthread_mutex_unlock(3), pthread_once(3),
pthread_rwlockattr_destroy(3), pthread_rwlockattr_getpshared(3),
pthread_rwlockattr_init(3), pthread_rwlockattr_setpshared(3),
pthread_rwlock_destroy(3), pthread_rwlock_init(3),
pthread_rwlock_rdlock(3), pthread_rwlock_timedrdlock(3),
pthread_rwlock_timedwrlock(3), pthread_rwlock_tryrdlock(3),
pthread_rwlock_trywrlock(3), pthread_rwlock_unlock(3),
pthread_rwlock_wrlock(3), pthread_self(3), pthread_setcancelstate(3),
pthread_setcanceltype(3), pthread_setconcurrency(3),
pthread_setschedparam(3), pthread_setspecific(3), pthread_sigmask(3),
pthread_spin_destroy(3), pthread_spin_init(3), pthread_spin_lock(3),
pthread_spin_trylock(3), pthread_spin_unlock(3), pthread_testcancel(3),
pthread_yield(3)
STANDARDS
The functions with the pthread_ prefix and not _np suffix or
pthread_rwlock prefix conform to ISO/IEC 9945-1:1996 ("POSIX.1").
The functions with the pthread_ prefix and _np suffix are non-portable
extensions to POSIX threads.
The functions with the pthread_rwlock prefix are extensions created by
The Open Group as part of the Version 2 of the Single UNIX Specification
("SUSv2").
DragonFly 5.7-DEVELOPMENT November 15, 2019 DragonFly 5.7-DEVELOPMENT