pthread.h File Reference

POSIX threads API (<pthread.h>) More...

#include <time.h>
#include <sched.h>
#include <zephyr/posix/sys/_pthreadtypes.h>
#include <zephyr/toolchain.h>

Include dependency graph for pthread.h:

Go to the source code of this file.

Macros
#define	PTHREAD_BARRIER_SERIAL_THREAD   1
	Returned by pthread_barrier_wait() to one (arbitrary) thread per barrier cycle.
#define	PTHREAD_CANCEL_ASYNCHRONOUS   1
	Thread cancellation is performed immediately.
#define	PTHREAD_CANCEL_ENABLE   0
	Cancellation is enabled (default).
#define	PTHREAD_CANCEL_DEFERRED   0
	Cancellation is deferred until a cancellation point (default).
#define	PTHREAD_CANCEL_DISABLE   1
	Cancellation delivery is disabled.
#define	PTHREAD_CANCELED   ((void *)-1)
	Value returned by pthread_join() for a cancelled thread.
#define	PTHREAD_CREATE_DETACHED   1
	Thread is created in the detached state.
#define	PTHREAD_CREATE_JOINABLE   0
	Thread is created in the joinable state (default).
#define	PTHREAD_EXPLICIT_SCHED   1
	Thread uses an explicitly provided scheduling policy.
#define	PTHREAD_INHERIT_SCHED   0
	Thread inherits the scheduling policy of its creator (default).
#define	PTHREAD_MUTEX_DEFAULT   3
	Default mutex type; behaviour on deadlock/unlock-by-non-owner is undefined.
#define	PTHREAD_MUTEX_ERRORCHECK   2
	Mutex that returns an error on deadlock or unlock by a non-owner.
#define	PTHREAD_MUTEX_NORMAL   0
	Non-recursive mutex with no error checks (fastest).
#define	PTHREAD_MUTEX_RECURSIVE   1
	Recursive mutex; the owning thread may lock it multiple times.
#define	PTHREAD_MUTEX_ROBUST   4
	Robust mutex; the state is recoverable if the owner dies.
#define	PTHREAD_MUTEX_STALLED   1
	Mutex is not recovered on owner death (default, for non-robust mutexes).
#define	PTHREAD_ONCE_INIT   _PTHREAD_ONCE_INITIALIZER
	Static initialiser for pthread_once_t objects.
#define	PTHREAD_PRIO_INHERIT   1
	Mutex protocol: owning thread inherits priority of highest-priority waiter.
#define	PTHREAD_PRIO_NONE   0
	Mutex protocol: no priority inheritance or ceiling.
#define	PTHREAD_PRIO_PROTECT   2
	Mutex protocol: owner runs at ceiling priority while holding the mutex.
#define	PTHREAD_PROCESS_SHARED   1
	Mutex or barrier attribute: object is shared between processes.
#define	PTHREAD_PROCESS_PRIVATE   0
	Mutex or barrier attribute: object is private to the process (default).
#define	PTHREAD_SCOPE_PROCESS   1
	Thread competes for resources only with threads in the same process.
#define	PTHREAD_SCOPE_SYSTEM   0
	Thread competes for resources with all threads in the system (default).
#define	PTHREAD_COND_INITIALIZER   _PTHREAD_COND_INITIALIZER
	Static initialiser for pthread_cond_t objects.
#define	PTHREAD_MUTEX_INITIALIZER   _PTHREAD_MUTEX_INITIALIZER
	Static initialiser for pthread_mutex_t objects.
#define	PTHREAD_RWLOCK_INITIALIZER   _PTHREAD_RWLOCK_INITIALIZER
	Static initialiser for pthread_rwlock_t objects.
#define	pthread_cleanup_push(_rtn, _arg)
	Push a cleanup handler onto the calling thread's cleanup stack.
#define	pthread_cleanup_pop(_ex)
	Pop a cleanup handler from the calling thread's cleanup stack.

Functions
int	pthread_atfork (void(*prepare)(void), void(*parent)(void), void(*child)(void))
	Register fork handlers to be called around fork().
int	pthread_attr_destroy (pthread_attr_t *attr)
	Destroy a thread attributes object.
int	pthread_attr_getdetachstate (const pthread_attr_t *attr, int *detachstate)
	Get the detach state attribute of a thread attributes object.
int	pthread_attr_getguardsize (const pthread_attr_t *ZRESTRICT attr, size_t *ZRESTRICT guardsize)
	Get the guard size attribute of a thread attributes object.
int	pthread_attr_getinheritsched (const pthread_attr_t *ZRESTRICT attr, int *ZRESTRICT inheritsched)
	Get the inherit-scheduler attribute of a thread attributes object.
int	pthread_attr_getschedparam (const pthread_attr_t *ZRESTRICT attr, struct sched_param *ZRESTRICT param)
	Get the scheduling parameter attribute of a thread attributes object.
int	pthread_attr_getschedpolicy (const pthread_attr_t *ZRESTRICT attr, int *ZRESTRICT policy)
	Get the scheduling policy attribute of a thread attributes object.
int	pthread_attr_getscope (const pthread_attr_t *ZRESTRICT attr, int *ZRESTRICT contentionscope)
	Get the contention scope attribute of a thread attributes object.
int	pthread_attr_getstack (const pthread_attr_t *ZRESTRICT attr, void **ZRESTRICT stackaddr, size_t *ZRESTRICT stacksize)
	Get the stack address and size attributes of a thread attributes object.
int	pthread_attr_getstacksize (const pthread_attr_t *ZRESTRICT attr, size_t *ZRESTRICT stacksize)
	Get the stack size attribute of a thread attributes object.
int	pthread_attr_init (pthread_attr_t *attr)
	Initialise a thread attributes object with default values.
int	pthread_attr_setdetachstate (pthread_attr_t *attr, int detachstate)
	Set the detach state attribute of a thread attributes object.
int	pthread_attr_setguardsize (pthread_attr_t *attr, size_t guardsize)
	Set the guard size attribute of a thread attributes object.
int	pthread_attr_setinheritsched (pthread_attr_t *attr, int inheritsched)
	Set the inherit-scheduler attribute of a thread attributes object.
int	pthread_attr_setschedparam (pthread_attr_t *ZRESTRICT attr, const struct sched_param *ZRESTRICT param)
	Set the scheduling parameter attribute of a thread attributes object.
int	pthread_attr_setschedpolicy (pthread_attr_t *attr, int policy)
	Set the scheduling policy attribute of a thread attributes object.
int	pthread_attr_setscope (pthread_attr_t *attr, int contentionscope)
	Set the contention scope attribute of a thread attributes object.
int	pthread_attr_setstack (pthread_attr_t *attr, void *stackaddr, size_t stacksize)
	Set the stack address and size attributes of a thread attributes object.
int	pthread_attr_setstacksize (pthread_attr_t *attr, size_t stacksize)
	Set the stack size attribute of a thread attributes object.
int	pthread_barrier_destroy (pthread_barrier_t *barrier)
	Destroy a barrier object.
int	pthread_barrier_init (pthread_barrier_t *ZRESTRICT barrier, const pthread_barrierattr_t *ZRESTRICT attr, unsigned int count)
	Initialise a barrier object.
int	pthread_barrier_wait (pthread_barrier_t *barrier)
	Synchronise participating threads at a barrier.
int	pthread_barrierattr_destroy (pthread_barrierattr_t *attr)
	Destroy a barrier attributes object.
int	pthread_barrierattr_getpshared (const pthread_barrierattr_t *ZRESTRICT attr, int *ZRESTRICT pshared)
	Get the process-shared attribute of a barrier attributes object.
int	pthread_barrierattr_init (pthread_barrierattr_t *attr)
	Initialise a barrier attributes object with default values.
int	pthread_barrierattr_setpshared (pthread_barrierattr_t *attr, int pshared)
	Set the process-shared attribute of a barrier attributes object.
int	pthread_cancel (pthread_t thread)
	Send a cancellation request to a thread.
int	pthread_cond_broadcast (pthread_cond_t *cond)
	Broadcast a condition variable, waking all waiting threads.
int	pthread_cond_clockwait (pthread_cond_t *ZRESTRICT cond, pthread_mutex_t *ZRESTRICT mutex, clockid_t clock_id, const struct timespec *ZRESTRICT abstime)
	Wait on a condition variable with a specific clock.
int	pthread_cond_destroy (pthread_cond_t *cond)
	Destroy a condition variable.
int	pthread_cond_init (pthread_cond_t *ZRESTRICT cond, const pthread_condattr_t *ZRESTRICT attr)
	Initialise a condition variable.
int	pthread_cond_signal (pthread_cond_t *cond)
	Signal a condition variable, waking at least one waiting thread.
int	pthread_cond_timedwait (pthread_cond_t *ZRESTRICT cond, pthread_mutex_t *ZRESTRICT mutex, const struct timespec *ZRESTRICT abstime)
	Wait on a condition variable with an absolute timeout (CLOCK_REALTIME).
int	pthread_cond_wait (pthread_cond_t *ZRESTRICT cond, pthread_mutex_t *ZRESTRICT mutex)
	Wait on a condition variable.
int	pthread_condattr_destroy (pthread_condattr_t *attr)
	Destroy a condition variable attributes object.
int	pthread_condattr_getclock (const pthread_condattr_t *ZRESTRICT attr, clockid_t *ZRESTRICT clock_id)
	Get the clock attribute of a condition variable attributes object.
int	pthread_condattr_getpshared (const pthread_condattr_t *ZRESTRICT attr, int *ZRESTRICT pshared)
	Get the process-shared attribute of a condition variable attributes object.
int	pthread_condattr_init (pthread_condattr_t *attr)
	Initialise a condition variable attributes object with default values.
int	pthread_condattr_setclock (pthread_condattr_t *attr, clockid_t clock_id)
	Set the clock attribute of a condition variable attributes object.
int	pthread_condattr_setpshared (pthread_condattr_t *attr, int pshared)
	Set the process-shared attribute of a condition variable attributes object.
int	pthread_create (pthread_t *ZRESTRICT thread, const pthread_attr_t *ZRESTRICT attr, void *(*start_routine)(void *), void *ZRESTRICT arg)
	Create a new thread.
int	pthread_detach (pthread_t thread)
	Detach a thread, releasing its resources automatically on termination.
int	pthread_equal (pthread_t t1, pthread_t t2)
	Compare two thread IDs.
void	pthread_exit (void *value_ptr)
	Terminate the calling thread.
int	pthread_getconcurrency (void)
	Get the concurrency level (advisory, has no effect on scheduling).
int	pthread_getcpuclockid (pthread_t thread_id, clockid_t *clock_id)
	Get the CPU-time clock of a thread.
int	pthread_getschedparam (pthread_t thread, int *ZRESTRICT policy, struct sched_param *ZRESTRICT param)
	Get the scheduling policy and parameters of a thread.
void *	pthread_getspecific (pthread_key_t key)
	Get the thread-specific value associated with a key.
int	pthread_join (pthread_t thread, void **value_ptr)
	Wait for a thread to terminate and retrieve its exit status.
int	pthread_key_create (pthread_key_t *key, void(*destructor)(void *))
	Create a thread-specific data key.
int	pthread_key_delete (pthread_key_t key)
	Delete a thread-specific data key.
int	pthread_mutex_consistent (pthread_mutex_t *mutex)
	Mark a robust mutex as consistent after recovering from owner death.
int	pthread_mutex_destroy (pthread_mutex_t *mutex)
	Destroy a mutex.
int	pthread_mutex_getprioceiling (const pthread_mutex_t *ZRESTRICT mutex, int *ZRESTRICT prioceiling)
	Get the priority ceiling of a mutex.
int	pthread_mutex_init (pthread_mutex_t *ZRESTRICT mutex, const pthread_mutexattr_t *ZRESTRICT attr)
	Initialise a mutex.
int	pthread_mutex_lock (pthread_mutex_t *mutex)
	Lock a mutex, blocking until it is available.
int	pthread_mutex_setprioceiling (pthread_mutex_t *ZRESTRICT mutex, int prioceiling, int *ZRESTRICT old_ceiling)
	Set the priority ceiling of a mutex.
int	pthread_mutex_timedlock (pthread_mutex_t *ZRESTRICT mutex, const struct timespec *ZRESTRICT abstime)
	Lock a mutex with an absolute timeout.
int	pthread_mutex_trylock (pthread_mutex_t *mutex)
	Try to lock a mutex without blocking.
int	pthread_mutex_unlock (pthread_mutex_t *mutex)
	Unlock a mutex.
int	pthread_mutexattr_destroy (pthread_mutexattr_t *attr)
	Destroy a mutex attributes object.
int	pthread_mutexattr_getprioceiling (const pthread_mutexattr_t *ZRESTRICT attr, int *ZRESTRICT prioceiling)
	Get the priority ceiling attribute of a mutex attributes object.
int	pthread_mutexattr_getprotocol (const pthread_mutexattr_t *ZRESTRICT attr, int *ZRESTRICT protocol)
	Get the protocol attribute of a mutex attributes object.
int	pthread_mutexattr_getpshared (const pthread_mutexattr_t *ZRESTRICT attr, int *ZRESTRICT pshared)
	Get the process-shared attribute of a mutex attributes object.
int	pthread_mutexattr_getrobust (const pthread_mutexattr_t *ZRESTRICT attr, int *ZRESTRICT robust)
	Get the robustness attribute of a mutex attributes object.
int	pthread_mutexattr_gettype (const pthread_mutexattr_t *ZRESTRICT attr, int *ZRESTRICT type)
	Get the type attribute of a mutex attributes object.
int	pthread_mutexattr_init (pthread_mutexattr_t *attr)
	Initialise a mutex attributes object with default values.
int	pthread_mutexattr_setprioceiling (pthread_mutexattr_t *attr, int prioceiling)
	Set the priority ceiling attribute of a mutex attributes object.
int	pthread_mutexattr_setprotocol (pthread_mutexattr_t *attr, int protocol)
	Set the protocol attribute of a mutex attributes object.
int	pthread_mutexattr_setpshared (pthread_mutexattr_t *attr, int pshared)
	Set the process-shared attribute of a mutex attributes object.
int	pthread_mutexattr_setrobust (pthread_mutexattr_t *attr, int robust)
	Set the robustness attribute of a mutex attributes object.
int	pthread_mutexattr_settype (pthread_mutexattr_t *attr, int type)
	Set the type attribute of a mutex attributes object.
int	pthread_once (pthread_once_t *once_control, void(*init_routine)(void))
	Ensure a one-time initialisation routine is called exactly once.
int	pthread_rwlock_destroy (pthread_rwlock_t *rwlock)
	Destroy a reader-writer lock.
int	pthread_rwlock_init (pthread_rwlock_t *ZRESTRICT rwlock, const pthread_rwlockattr_t *ZRESTRICT attr)
	Initialise a reader-writer lock.
int	pthread_rwlock_rdlock (pthread_rwlock_t *rwlock)
	Acquire a read lock, blocking until available.
int	pthread_rwlock_timedrdlock (pthread_rwlock_t *ZRESTRICT rwlock, const struct timespec *ZRESTRICT abstime)
	Acquire a read lock with an absolute timeout.
int	pthread_rwlock_timedwrlock (pthread_rwlock_t *ZRESTRICT rwlock, const struct timespec *ZRESTRICT abstime)
	Acquire a write lock with an absolute timeout.
int	pthread_rwlock_tryrdlock (pthread_rwlock_t *rwlock)
	Try to acquire a read lock without blocking.
int	pthread_rwlock_trywrlock (pthread_rwlock_t *rwlock)
	Try to acquire a write lock without blocking.
int	pthread_rwlock_unlock (pthread_rwlock_t *rwlock)
	Release a reader-writer lock.
int	pthread_rwlock_wrlock (pthread_rwlock_t *rwlock)
	Acquire a write lock, blocking until available.
int	pthread_rwlockattr_destroy (pthread_rwlockattr_t *attr)
	Destroy a reader-writer lock attributes object.
int	pthread_rwlockattr_getpshared (const pthread_rwlockattr_t *ZRESTRICT attr, int *ZRESTRICT pshared)
	Get the process-shared attribute of a reader-writer lock attributes object.
int	pthread_rwlockattr_init (pthread_rwlockattr_t *attr)
	Initialise a reader-writer lock attributes object with default values.
int	pthread_rwlockattr_setpshared (pthread_rwlockattr_t *attr, int pshared)
	Set the process-shared attribute of a reader-writer lock attributes object.
pthread_t	pthread_self (void)
	Return the thread ID of the calling thread.
int	pthread_setcancelstate (int state, int *oldstate)
	Set the cancellability state of the calling thread.
int	pthread_setcanceltype (int type, int *oldtype)
	Set the cancellability type of the calling thread.
int	pthread_setconcurrency (int new_level)
	Set the concurrency level (advisory, has no effect on scheduling).
int	pthread_setschedparam (pthread_t thread, int policy, const struct sched_param *param)
	Set the scheduling policy and parameters of a thread.
int	pthread_setschedprio (pthread_t thread, int prio)
	Set the scheduling priority of a thread.
int	pthread_setspecific (pthread_key_t key, const void *value)
	Set the thread-specific value associated with a key.
int	pthread_spin_destroy (pthread_spinlock_t *lock)
	Destroy a spin lock.
int	pthread_spin_init (pthread_spinlock_t *lock, int pshared)
	Initialise a spin lock.
int	pthread_spin_lock (pthread_spinlock_t *lock)
	Acquire a spin lock, busy-waiting until available.
int	pthread_spin_trylock (pthread_spinlock_t *lock)
	Try to acquire a spin lock without busy-waiting.
int	pthread_spin_unlock (pthread_spinlock_t *lock)
	Release a spin lock.
void	pthread_testcancel (void)
	Create a cancellation point in the calling thread.
int	pthread_getname_np (pthread_t thread, char *name, size_t len)
	Get the name of a thread (GNU extension).
int	pthread_setname_np (pthread_t thread, const char *name)
	Set the name of a thread (GNU extension).
int	pthread_timedjoin_np (pthread_t thread, void **status, const struct timespec *abstime)
	Wait for a thread to terminate with an absolute timeout (GNU extension).
int	pthread_tryjoin_np (pthread_t thread, void **status)
	Try to join a thread without blocking (GNU extension).

Detailed Description

POSIX threads API (<pthread.h>)

Covers thread lifecycle, attributes, cancellation, scheduling, mutexes, condition variables, barriers, reader-writer locks, spin locks, and thread-specific data.

See also

POSIX.1-2017 <pthread.h>

Definition in file pthread.h.