Amazon FreeRTOS: POSIX
Return to main page ↑
pthread.h File Reference

Threads. More...

Go to the source code of this file.

Macros

pthread detach state.
#define PTHREAD_CREATE_DETACHED   0
 
#define PTHREAD_CREATE_JOINABLE   1
 
Returned to a single thread after a successful pthread_barrier_wait.

POSIX specifies that "The constant PTHREAD_BARRIER_SERIAL_THREAD is defined in <pthread.h> and its value shall be distinct from any other value returned by pthread_barrier_wait()." So it's defined as negative to distinguish it from the errnos, which are positive.

#define PTHREAD_BARRIER_SERIAL_THREAD   ( -2 )
 
Mutex types.
#define PTHREAD_MUTEX_NORMAL   0
 
#define PTHREAD_MUTEX_ERRORCHECK   1
 
#define PTHREAD_MUTEX_RECURSIVE   2
 
#define PTHREAD_MUTEX_DEFAULT   PTHREAD_MUTEX_NORMAL
 

Functions

int pthread_attr_destroy (pthread_attr_t *attr)
 Destroy the thread attributes object. More...
 
int pthread_attr_getdetachstate (const pthread_attr_t *attr, int *detachstate)
 Get detachstate attribute. More...
 
int pthread_attr_getschedparam (const pthread_attr_t *attr, struct sched_param *param)
 Get schedparam attribute. More...
 
int pthread_attr_getstacksize (const pthread_attr_t *attr, size_t *stacksize)
 Get stacksize attribute. More...
 
int pthread_attr_init (pthread_attr_t *attr)
 Initialize the thread attributes object. More...
 
int pthread_attr_setdetachstate (pthread_attr_t *attr, int detachstate)
 Set detachstate attribute. More...
 
int pthread_attr_setschedparam (pthread_attr_t *attr, const struct sched_param *param)
 Set schedparam attribute. More...
 
int pthread_attr_setschedpolicy (pthread_attr_t *attr, int policy)
 Set the schedpolicy attribute. More...
 
int pthread_attr_setstacksize (pthread_attr_t *attr, size_t stacksize)
 Set stacksize attribute. More...
 
int pthread_barrier_destroy (pthread_barrier_t *barrier)
 Destroy a barrier object. More...
 
int pthread_barrier_init (pthread_barrier_t *barrier, const pthread_barrierattr_t *attr, unsigned count)
 Initialize a barrier object. More...
 
int pthread_barrier_wait (pthread_barrier_t *barrier)
 Synchronize at a barrier. More...
 
int pthread_create (pthread_t *thread, const pthread_attr_t *attr, void *(*startroutine)(void *), void *arg)
 Thread creation. More...
 
int pthread_cond_broadcast (pthread_cond_t *cond)
 Broadcast a condition. More...
 
int pthread_cond_destroy (pthread_cond_t *cond)
 Destroy condition variables. More...
 
int pthread_cond_init (pthread_cond_t *cond, const pthread_condattr_t *attr)
 Initialize condition variables. More...
 
int pthread_cond_signal (pthread_cond_t *cond)
 Signal a condition. More...
 
int pthread_cond_timedwait (pthread_cond_t *cond, pthread_mutex_t *mutex, const struct timespec *abstime)
 Wait on a condition with a timeout. More...
 
int pthread_cond_wait (pthread_cond_t *cond, pthread_mutex_t *mutex)
 Wait on a condition. More...
 
int pthread_equal (pthread_t t1, pthread_t t2)
 Compare thread IDs. More...
 
void pthread_exit (void *value_ptr)
 Thread termination. More...
 
int pthread_getschedparam (pthread_t thread, int *policy, struct sched_param *param)
 Dynamic thread scheduling parameters access. More...
 
int pthread_join (pthread_t thread, void **retval)
 Wait for thread termination. More...
 
int pthread_mutex_destroy (pthread_mutex_t *mutex)
 Destroy a mutex. More...
 
int pthread_mutex_init (pthread_mutex_t *mutex, const pthread_mutexattr_t *attr)
 Initialize a mutex. More...
 
int pthread_mutex_lock (pthread_mutex_t *mutex)
 Lock a mutex. More...
 
int pthread_mutex_timedlock (pthread_mutex_t *mutex, const struct timespec *abstime)
 Lock a mutex with timeout. More...
 
int pthread_mutex_trylock (pthread_mutex_t *mutex)
 Attempt to lock a mutex. Fail immediately if mutex is already locked. More...
 
int pthread_mutex_unlock (pthread_mutex_t *mutex)
 Unlock a mutex. More...
 
int pthread_mutexattr_destroy (pthread_mutexattr_t *attr)
 Destroy the mutex attributes object. More...
 
int pthread_mutexattr_gettype (const pthread_mutexattr_t *attr, int *type)
 Get the mutex type attribute. More...
 
int pthread_mutexattr_init (pthread_mutexattr_t *attr)
 Initialize the mutex attributes object. More...
 
int pthread_mutexattr_settype (pthread_mutexattr_t *attr, int type)
 Set the mutex type attribute. More...
 
pthread_t pthread_self (void)
 Get the calling thread ID. More...
 
int pthread_setschedparam (pthread_t thread, int policy, const struct sched_param *param)
 Dynamic thread scheduling parameters access. More...
 

Detailed Description

Macro Definition Documentation

◆ PTHREAD_CREATE_DETACHED

#define PTHREAD_CREATE_DETACHED   0

Detached.

◆ PTHREAD_CREATE_JOINABLE

#define PTHREAD_CREATE_JOINABLE   1

Joinable (default).

◆ PTHREAD_MUTEX_NORMAL

#define PTHREAD_MUTEX_NORMAL   0

Non-robust, deadlock on relock, does not remember owner.

◆ PTHREAD_MUTEX_ERRORCHECK

#define PTHREAD_MUTEX_ERRORCHECK   1

Non-robust, error on relock, remembers owner.

◆ PTHREAD_MUTEX_RECURSIVE

#define PTHREAD_MUTEX_RECURSIVE   2

Non-robust, recursive relock, remembers owner.

◆ PTHREAD_MUTEX_DEFAULT

#define PTHREAD_MUTEX_DEFAULT   PTHREAD_MUTEX_NORMAL

PTHREAD_MUTEX_NORMAL (default).

Function Documentation

◆ pthread_attr_destroy()

int pthread_attr_destroy ( pthread_attr_t attr)

Destroy the thread attributes object.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_destroy.html
Return values
0- Upon successful completion.

◆ pthread_attr_getdetachstate()

int pthread_attr_getdetachstate ( const pthread_attr_t attr,
int *  detachstate 
)

Get detachstate attribute.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_getdetachstate.html
Return values
0- Upon successful completion.

◆ pthread_attr_getschedparam()

int pthread_attr_getschedparam ( const pthread_attr_t attr,
struct sched_param param 
)

Get schedparam attribute.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_getschedparam.html
Return values
0- Upon successful completion.

◆ pthread_attr_getstacksize()

int pthread_attr_getstacksize ( const pthread_attr_t attr,
size_t *  stacksize 
)

Get stacksize attribute.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_getstacksize.html
Return values
0- Upon successful completion.

◆ pthread_attr_init()

int pthread_attr_init ( pthread_attr_t attr)

Initialize the thread attributes object.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_init.html
Return values
0- Upon successful completion.
Note
Currently, only stack size, sched_param, and detach state attributes are supported. Also see pthread_attr_get*() and pthread_attr_set*().

◆ pthread_attr_setdetachstate()

int pthread_attr_setdetachstate ( pthread_attr_t attr,
int  detachstate 
)

Set detachstate attribute.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_setdetachstate.html
Return values
0- Upon successful completion
EINVAL- The value of detachstate is not valid. Currently, supported detach states are – PTHREAD_CREATE_DETACHED and PTHREAD_CREATE_JOINABLE.

◆ pthread_attr_setschedparam()

int pthread_attr_setschedparam ( pthread_attr_t attr,
const struct sched_param param 
)

Set schedparam attribute.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_setschedparam.html
Return values
0- Upon successful completion.
EINVAL- The value of param is not valid.
ENOTSUP- An attempt was made to set the attribute to an unsupported value.

◆ pthread_attr_setschedpolicy()

int pthread_attr_setschedpolicy ( pthread_attr_t attr,
int  policy 
)

Set the schedpolicy attribute.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_setschedpolicy.html

Return values
0- Upon successful completion.
Warning
This function is a stub and always returns 0.

◆ pthread_attr_setstacksize()

int pthread_attr_setstacksize ( pthread_attr_t attr,
size_t  stacksize 
)

Set stacksize attribute.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_setstacksize.html
Return values
0- Upon successful completion.
EINVAL- The value of stacksize is less than {PTHREAD_STACK_MIN}.

◆ pthread_barrier_destroy()

int pthread_barrier_destroy ( pthread_barrier_t barrier)

Destroy a barrier object.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_barrier_destroy.html
Return values
0- Upon successful completion.
Note
This function does not validate whether there is any thread blocking on the barrier before destroying.

◆ pthread_barrier_init()

int pthread_barrier_init ( pthread_barrier_t barrier,
const pthread_barrierattr_t attr,
unsigned  count 
)

Initialize a barrier object.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_barrier_init.html
Return values
0- Upon successful completion.
EINVAL- The value specified by count is equal to zero.
ENOMEM- count cannot fit into FreeRTOS event group type OR insufficient memory exists to initialize the barrier.
Note
attr is ignored.
pthread_barrier_init() is implemented with FreeRTOS event group. To ensure count fits in event group, count may be at most 8 when configUSE_16_BIT_TICKS is 1; it may be at most 24 otherwise. configUSE_16_BIT_TICKS is configured in application FreeRTOSConfig.h file, which defines how many bits tick count type has. See further details and limitation about event group and configUSE_16_BIT_TICKS in FreeRTOS site.

◆ pthread_barrier_wait()

int pthread_barrier_wait ( pthread_barrier_t barrier)

Synchronize at a barrier.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_barrier_wait.html
Return values
PTHREAD_BARRIER_SERIAL_THREAD- Upon successful completion, the first thread.
0- Upon successful completion, other thread(s).

◆ pthread_create()

int pthread_create ( pthread_t thread,
const pthread_attr_t attr,
void *(*)(void *)  startroutine,
void *  arg 
)

Thread creation.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_create.html
Return values
0- Upon successful completion.
EAGAIN- Insufficient memory for either thread structure or task creation.

◆ pthread_cond_broadcast()

int pthread_cond_broadcast ( pthread_cond_t cond)

Broadcast a condition.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_broadcast.html
Return values
0- Upon successful completion.

◆ pthread_cond_destroy()

int pthread_cond_destroy ( pthread_cond_t cond)

Destroy condition variables.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_destroy.html
Return values
0- Upon successful completion.

◆ pthread_cond_init()

int pthread_cond_init ( pthread_cond_t cond,
const pthread_condattr_t attr 
)

Initialize condition variables.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_init.html
Return values
0- Upon successful completion.
ENOMEM- Insufficient memory exists to initialize the condition variable.
Note
attr is ignored and treated as NULL. Default setting is always used.

◆ pthread_cond_signal()

int pthread_cond_signal ( pthread_cond_t cond)

Signal a condition.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_signal.html
Return values
0- Upon successful completion.

◆ pthread_cond_timedwait()

int pthread_cond_timedwait ( pthread_cond_t cond,
pthread_mutex_t mutex,
const struct timespec abstime 
)

Wait on a condition with a timeout.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_timedwait.html
Return values
0- Upon successful completion.
EINVAL- The abstime argument passed in does not refer to an initialized structure OR the abstime parameter specified a nanoseconds field value less than zero or greater than or equal to 1000 million.
ETIMEDOUT- The time specified by abstime to pthread_cond_timedwait() has passed.

◆ pthread_cond_wait()

int pthread_cond_wait ( pthread_cond_t cond,
pthread_mutex_t mutex 
)

Wait on a condition.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_cond_wait.html
Return values
0- Upon successful completion.

◆ pthread_equal()

int pthread_equal ( pthread_t  t1,
pthread_t  t2 
)

Compare thread IDs.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_equal.html
Return values
0- t1 and t2 are both not NULL && equal.
non-zero- otherwise.

◆ pthread_exit()

void pthread_exit ( void *  value_ptr)

Thread termination.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_exit.html
Return values
void- this function cannot return to its caller.

◆ pthread_getschedparam()

int pthread_getschedparam ( pthread_t  thread,
int *  policy,
struct sched_param param 
)

Dynamic thread scheduling parameters access.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_getschedparam.html
Return values
0- Upon successful completion.
Note
policy is always set to SCHED_OTHER by this function.

◆ pthread_join()

int pthread_join ( pthread_t  thread,
void **  retval 
)

Wait for thread termination.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_join.html
Return values
0- Upon successful completion.
EDEADLK- The value specified by the thread argument to pthread_join() does not refer to a joinable thread OR multiple simultaneous calls to pthread_join() specifying the same target thread OR the value specified by the thread argument to pthread_join() refers to the calling thread.

◆ pthread_mutex_destroy()

int pthread_mutex_destroy ( pthread_mutex_t mutex)

Destroy a mutex.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_destroy.html
Return values
0- Upon successful completion.
Note
If there exists a thread holding this mutex, this function returns 0 with mutex not being destroyed.

◆ pthread_mutex_init()

int pthread_mutex_init ( pthread_mutex_t mutex,
const pthread_mutexattr_t attr 
)

Initialize a mutex.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_init.html
Return values
0- Upon successful completion.
ENOMEM- Insufficient memory exists to initialize the mutex structure.
EAGAIN- Unable to initialize the mutex structure member(s).

◆ pthread_mutex_lock()

int pthread_mutex_lock ( pthread_mutex_t mutex)

Lock a mutex.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_lock.html
Return values
0- Upon successful completion.
EINVAL- the abstime parameter specified a nanoseconds field value less than zero or greater than or equal to 1000 million.
EDEADLK- The mutex type is PTHREAD_MUTEX_ERRORCHECK and the current thread already owns the mutex.

◆ pthread_mutex_timedlock()

int pthread_mutex_timedlock ( pthread_mutex_t mutex,
const struct timespec abstime 
)

Lock a mutex with timeout.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_timedlock.html
Return values
0- Upon successful completion.
EINVAL- The abstime argument passed in does not refer to an initialized structure OR the abstime parameter specified a nanoseconds field value less than zero or greater than or equal to 1000 million.
EDEADLK- The mutex type is PTHREAD_MUTEX_ERRORCHECK and the current thread already owns the mutex.
ETIMEDOUT- The mutex could not be locked before the specified timeout expired.

◆ pthread_mutex_trylock()

int pthread_mutex_trylock ( pthread_mutex_t mutex)

Attempt to lock a mutex. Fail immediately if mutex is already locked.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_trylock.html
Return values
0- Upon successful completion.
EINVAL- the abstime parameter specified a nanoseconds field value less than zero or greater than or equal to 1000 million.
EDEADLK- The mutex type is PTHREAD_MUTEX_ERRORCHECK and the current thread already owns the mutex.
EBUSY- The mutex could not be acquired because it was already locked.

◆ pthread_mutex_unlock()

int pthread_mutex_unlock ( pthread_mutex_t mutex)

Unlock a mutex.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_unlock.html
Return values
0- Upon successful completion.
EPERM- The mutex type is PTHREAD_MUTEX_ERRORCHECK or PTHREAD_MUTEX_RECURSIVE, and the current thread does not own the mutex.

◆ pthread_mutexattr_destroy()

int pthread_mutexattr_destroy ( pthread_mutexattr_t attr)

Destroy the mutex attributes object.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutexattr_destroy.html
Return values
0- Upon successful completion.

◆ pthread_mutexattr_gettype()

int pthread_mutexattr_gettype ( const pthread_mutexattr_t attr,
int *  type 
)

Get the mutex type attribute.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutexattr_gettype.html
Return values
0- Upon successful completion.

◆ pthread_mutexattr_init()

int pthread_mutexattr_init ( pthread_mutexattr_t attr)

Initialize the mutex attributes object.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutexattr_init.html
Return values
0- Upon successful completion.
Note
Currently, only the type attribute is supported. Also see pthread_mutexattr_settype() and pthread_mutexattr_gettype().

◆ pthread_mutexattr_settype()

int pthread_mutexattr_settype ( pthread_mutexattr_t attr,
int  type 
)

Set the mutex type attribute.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutexattr_settype.html
Return values
0- Upon successful completion.
EINVAL- The value type is invalid.

◆ pthread_self()

pthread_t pthread_self ( void  )

Get the calling thread ID.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_self.html
Return values
thethread ID of the calling thread.

◆ pthread_setschedparam()

int pthread_setschedparam ( pthread_t  thread,
int  policy,
const struct sched_param param 
)

Dynamic thread scheduling parameters access.

See also
http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_setschedparam.html
Note
policy is ignored; only priority (param.sched_priority) may be changed.
Return values
0- Upon successful completion.