Skip to main content

Posix Threads (pthread)

Functions#

Name
intpthread_attr_getdetachstate(const pthread_attr_t attr, int detachstate)
intpthread_attr_setdetachstate(pthread_attr_t * attr, int detachstate)
intpthread_attr_getguardsize(const pthread_attr_t attr, size_t guardsize)
intpthread_attr_setguardsize(pthread_attr_t * attr, size_t guardsize)
intpthread_attr_getinheritsched(const pthread_attr_t attr, int inheritsched)
intpthread_attr_setinheritsched(pthread_attr_t * attr, int inheritsched)
intpthread_attr_getschedparam(const pthread_attr_t attr, struct sched_param param)
intpthread_attr_setschedparam(pthread_attr_t attr, const struct sched_param param)
intpthread_attr_getschedpolicy(const pthread_attr_t attr, int policy)
intpthread_attr_setschedpolicy(pthread_attr_t * attr, int policy)
intpthread_attr_getscope(const pthread_attr_t attr, int contentionscope)
intpthread_attr_setscope(pthread_attr_t * attr, int contentionscope)
intpthread_attr_getstacksize(const pthread_attr_t attr, size_t stacksize)
intpthread_attr_setstacksize(pthread_attr_t * attr, size_t stacksize)
intpthread_attr_getstackaddr(const pthread_attr_t * attr, void ** stackaddr)
intpthread_attr_setstackaddr(pthread_attr_t attr, void stackaddr)
intpthread_attr_init(pthread_attr_t * attr)
intpthread_attr_destroy(pthread_attr_t * attr)
intpthread_cancel(pthread_t thread)
intpthread_setcancelstate(int state, int * oldstate)
intpthread_setcanceltype(int type, int * oldtype)
voidpthread_testcancel()
intpthread_cond_init(pthread_cond_t cond, const pthread_condattr_t attr)
intpthread_cond_destroy(pthread_cond_t * cond)
intpthread_cond_broadcast(pthread_cond_t * cond)
intpthread_cond_signal(pthread_cond_t * cond)
intpthread_cond_wait(pthread_cond_t cond, pthread_mutex_t mutex)
intpthread_cond_timedwait(pthread_cond_t cond, pthread_mutex_t mutex, const struct timespec * abstime)
intpthread_condattr_init(pthread_condattr_t * attr)
intpthread_condattr_destroy(pthread_condattr_t * attr)
intpthread_condattr_getpshared(const pthread_condattr_t attr, int pshared)
intpthread_condattr_setpshared(pthread_condattr_t * attr, int pshared)
intpthread_condattr_getclock(const pthread_condattr_t attr, clockid_t clock_id)
intpthread_condattr_setclock(pthread_condattr_t * attr, clockid_t clock_id)
intpthread_create(pthread_t thread, const pthread_attr_t attr, void ()(void ) start_routine, void arg)
intpthread_join(pthread_t thread, void ** value_ptr)
voidpthread_exit(void * value_ptr)
intpthread_mutex_lock(pthread_mutex_t * mutex)
intpthread_mutex_trylock(pthread_mutex_t * mutex)
intpthread_mutex_unlock(pthread_mutex_t * mutex)
intpthread_mutex_destroy(pthread_mutex_t * mutex)
intpthread_mutex_timedlock(pthread_mutex_t mutex, const struct timespec abs_timeout)
intpthread_mutex_getprioceiling(pthread_mutex_t mutex, int prioceiling)
intpthread_mutex_setprioceiling(pthread_mutex_t mutex, int prioceiling, int old_ceiling)
intpthread_mutex_init(pthread_mutex_t mutex, const pthread_mutexattr_t attr)
intpthread_mutexattr_getprioceiling(const pthread_mutexattr_t attr, int prioceiling)
intpthread_mutexattr_setprioceiling(pthread_mutexattr_t * attr, int prio_ceiling)
intpthread_mutexattr_getprotocol(const pthread_mutexattr_t attr, int protocol)
intpthread_mutexattr_setprotocol(pthread_mutexattr_t * attr, int protocol)
intpthread_mutexattr_getpshared(const pthread_mutexattr_t attr, int pshared)
intpthread_mutexattr_setpshared(pthread_mutexattr_t * attr, int pshared)
intpthread_mutexattr_gettype(const pthread_mutexattr_t attr, int type)
intpthread_mutexattr_settype(pthread_mutexattr_t * attr, int type)
intpthread_mutexattr_init(pthread_mutexattr_t * attr)
intpthread_mutexattr_destroy(pthread_mutexattr_t * attr)
intpthread_getschedparam(pthread_t thread, int policy, struct sched_param param)
intpthread_setschedparam(pthread_t thread, int policy, struct sched_param * param)
pthread_tpthread_self()

Functions Documentation#

pthread_attr_getdetachstate#

int pthread_attr_getdetachstate(    const pthread_attr_t * attr,    int * detachstate)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr does not refer to an initialized thread attribute object

This function gets the detach state from attr and stores it in detachstate.

pthread_attr_setdetachstate#

int pthread_attr_setdetachstate(    pthread_attr_t * attr,    int detachstate)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr does not refer to an initialized thread attribute object
  • EINVAL: detachstate is not a valid

This function sets the detach state in attr with detachstate.

pthread_attr_getguardsize#

int pthread_attr_getguardsize(    const pthread_attr_t * attr,    size_t * guardsize)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr does not refer to an initialized thread attribute object

This function gets the guard size from attr and stores it in guardsize.

pthread_attr_setguardsize#

int pthread_attr_setguardsize(    pthread_attr_t * attr,    size_t guardsize)

Return: -1 with errno (see Errno) set to ENOTSUP

This function is not supported. The guard size is a fixed value that cannot be set by the user.

pthread_attr_getinheritsched#

int pthread_attr_getinheritsched(    const pthread_attr_t * attr,    int * inheritsched)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr does not refer to an initialized thread attribute object

This function gets the inherit sched value from attr and stores it in inheritsched.

pthread_attr_setinheritsched#

int pthread_attr_setinheritsched(    pthread_attr_t * attr,    int inheritsched)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr does not refer to an initialized thread attribute object
  • EINVAL: inheritsched is not a valid value

This function sets the inherit sched in attr with inheritsched.

pthread_attr_getschedparam#

int pthread_attr_getschedparam(    const pthread_attr_t * attr,    struct sched_param * param)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr does not refer to an initialized thread attribute object

This function gets the scheduling parameters from attr and stores it in param.

pthread_attr_setschedparam#

int pthread_attr_setschedparam(    pthread_attr_t * attr,    const struct sched_param * param)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr does not refer to an initialized thread attribute object

This function sets the scheduling parameters in attr with param.

pthread_attr_getschedpolicy#

int pthread_attr_getschedpolicy(    const pthread_attr_t * attr,    int * policy)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr does not refer to an initialized thread attribute object

This function gets the scheduling policy from attr and stores it in policy.

pthread_attr_setschedpolicy#

int pthread_attr_setschedpolicy(    pthread_attr_t * attr,    int policy)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr does not refer to an initialized thread attribute object
  • EINVAL: policy does not refer to a valid policy.

This function sets the scheduling policy in attr with policy.

pthread_attr_getscope#

int pthread_attr_getscope(    const pthread_attr_t * attr,    int * contentionscope)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr does not refer to an initialized thread attribute object

This function gets the contention scope from attr and stores it in contentionscope.

pthread_attr_setscope#

int pthread_attr_setscope(    pthread_attr_t * attr,    int contentionscope)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr does not refer to an initialized thread attribute object
  • ENOTSUP: contentionscope is not PTHREAD_SCOPE_SYSTEM or PTHREAD_SCOPE_PROCESS

This function sets the contention scope in attr with contentionscope.

pthread_attr_getstacksize#

int pthread_attr_getstacksize(    const pthread_attr_t * attr,    size_t * stacksize)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr does not refer to an initialized thread attribute object

This functions gets the stack size from attr and stores it in stacksize.

pthread_attr_setstacksize#

int pthread_attr_setstacksize(    pthread_attr_t * attr,    size_t stacksize)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr does not refer to an initialized thread attribute object
  • EINVAL: stacksize is too low of a value
  • ENOMEM: not enough memory

This function sets the stack size in attr with stacksize.

pthread_attr_getstackaddr#

int pthread_attr_getstackaddr(    const pthread_attr_t * attr,    void ** stackaddr)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr does not refer to an initialized thread attribute object

This functions gets the stack address from attr and stores it in stackaddr.

pthread_attr_setstackaddr#

int pthread_attr_setstackaddr(    pthread_attr_t * attr,    void * stackaddr)

Return: -1 with errno equal to ENOTSUP

This function is not supported.

pthread_attr_init#

int pthread_attr_init(    pthread_attr_t * attr)

Return: 0 on success

This function initializes attr to the default values.

pthread_attr_destroy#

int pthread_attr_destroy(    pthread_attr_t * attr)

Parameters:

  • attr A pointer to the attributes to destroy

Return: 0 on success or -1 and errno set to:

  • EINVAL: attr is NULL or uninitialized

Destroys the pthead attributes.

This function frees the stack associated with the thread. The attributes should not be destroyed until the thread is done executing.

pthread_cancel#

int pthread_cancel(    pthread_t thread)

Return: Zero on success or -1 with errno set.

This function cancels the specified thread.

pthread_setcancelstate#

int pthread_setcancelstate(    int state,    int * oldstate)

Return: -1 with errno equal to ENOTSUP

sets the cancel state of the calling thread.

pthread_setcanceltype#

int pthread_setcanceltype(    int type,    int * oldtype)

Return: Zero on success or -1 with errno set to:

  • ENOTSUP: type is PTHREAD_CANCEL_ASYNCHRONOUS which is not supported
  • EINVAL: type is not PTHREAD_CANCEL_DEFERRED which is not supported

Sets the cancel type of the calling thread.

pthread_testcancel#

void pthread_testcancel()

pthread_cond_init#

int pthread_cond_init(    pthread_cond_t * cond,    const pthread_condattr_t * attr)

Return: Zero on success or -1 with errno set to:

  • EINVAL: cond or attr is NULL

This function initializes a pthread block condition.

pthread_cond_destroy#

int pthread_cond_destroy(    pthread_cond_t * cond)

Return: Zero on success or -1 with errno set to:

  • EINVAL: cond is NULL

This function destroys a pthread block condition.

pthread_cond_broadcast#

int pthread_cond_broadcast(    pthread_cond_t * cond)

Return: Zero on success or -1 with errno set to:

  • EINVAL: cond is NULL or not initialized

This function wakes all threads that are blocked on cond.

pthread_cond_signal#

int pthread_cond_signal(    pthread_cond_t * cond)

Return: Zero on success or -1 with errno set to:

  • EINVAL: cond is NULL or not initialized

This function wakes the highest priority thread that is blocked on cond.

pthread_cond_wait#

int pthread_cond_wait(    pthread_cond_t * cond,    pthread_mutex_t * mutex)

Return: Zero on success or -1 with errno set to:

  • EINVAL: cond is NULL or not initialized
  • EACCES: cond is from a different process and not shared
  • EPERM: the caller does not have a lock on mutex

This function causes the calling thread to block on cond. When called, mutex must be locked by the caller.

pthread_cond_timedwait#

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

Return: Zero on success or -1 with errno set to:

  • EINVAL: cond is NULL or not initialized
  • EACCES: cond is from a different process and not shared
  • EPERM: the caller does not have a lock on mutex
  • ETIMEDOUT: abstime passed before cond arrived

This function causes the calling thread to block on cond. When called, mutex must be locked by the caller. If cond does not wake the process by abstime, the thread resumes.

Example:

struct timespec abstime;clock_gettime(CLOCK_REALTIME, &abstime);abstime.tv_sec += 5; //time out after five secondsif ( pthread_cond_timedwait(cond, mutex, &abstime) == -1 ){     if ( errno == ETIMEDOUT ){          //Timedout     } else {          //Failed     }}

pthread_condattr_init#

int pthread_condattr_init(    pthread_condattr_t * attr)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr is NULL

This function initializes attr with the default values.

pthread_condattr_destroy#

int pthread_condattr_destroy(    pthread_condattr_t * attr)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr is not an initialized condition attribute

This function destroys attr.

pthread_condattr_getpshared#

int pthread_condattr_getpshared(    const pthread_condattr_t * attr,    int * pshared)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr is not an initialized condition attribute

This function gets the pshared value for attr and stores it in pshared.

pthread_condattr_setpshared#

int pthread_condattr_setpshared(    pthread_condattr_t * attr,    int pshared)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr is not an initialized condition attribute
  • EINVAL: pshared is not PTHREAD_PROCESS_SHARED or PTHREAD_PROCESS_PRIVATE

This function sets the pshared value in attr to pshared.

pthread_condattr_getclock#

int pthread_condattr_getclock(    const pthread_condattr_t * attr,    clockid_t * clock_id)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr is not an initialized condition attribute

This function gets the clock associated with pthread_cond_timedwait() operations.

pthread_condattr_setclock#

int pthread_condattr_setclock(    pthread_condattr_t * attr,    clockid_t clock_id)

Return: -1 with errno set to:

  • ENOTSUP: this function is not supported

pthread_cond_timedwait() operations always use CLOCK_REALTIME. This value cannot be changed.

pthread_create#

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

Return: Zero on success or -1 with errno (see Errno) set to:

  • ENOMEM: error allocating memory for the thread
  • EAGAIN: insufficient system resources to create a new thread

This function creates a new thread.

pthread_join#

int pthread_join(    pthread_t thread,    void ** value_ptr)

Return: Zero on success or -1 with errno (see Errno) set to:

  • ESRCH: thread does not exist
  • EDEADLK: a deadlock has been detected or thread refers to the calling thread
  • EINVAL: thread does not refer to a joinable thread.

This function blocks the calling thread until thread terminates.

pthread_exit#

void pthread_exit(    void * value_ptr)

pthread_mutex_lock#

int pthread_mutex_lock(    pthread_mutex_t * mutex)

Return: Zero on success or -1 with errno set to:

  • EINVAL: mutex is NULL
  • EDEADLK: the caller already holds the mutex
  • ETIMEDOUT: abstime passed before cond arrived

This function locks mutex. If mutex cannot be locked immediately, the thread is blocked until mutex is available.

pthread_mutex_trylock#

int pthread_mutex_trylock(    pthread_mutex_t * mutex)

Return: Zero on success or -1 with errno set to:

  • EINVAL: mutex is NULL
  • EBUSY: mutex is locked by another thread

This function tries to lock mutex. If mutex cannot be locked immediately, the function returns without the lock.

pthread_mutex_unlock#

int pthread_mutex_unlock(    pthread_mutex_t * mutex)

Return: Zero on success or -1 with errno set to:

  • EINVAL: mutex is NULL
  • EACCES: the caller does not have a lock on mutex

This function unlocks mutex.

pthread_mutex_destroy#

int pthread_mutex_destroy(    pthread_mutex_t * mutex)

Return: Zero on success or -1 with errno set to:

  • EINVAL: mutex is NULL

This function destroys mutex.

pthread_mutex_timedlock#

int pthread_mutex_timedlock(    pthread_mutex_t * mutex,    const struct timespec * abs_timeout)

Return: Zero on success or -1 with errno set to:

  • EINVAL: mutex or abs_timeout is NULL
  • EDEADLK: the caller already holds the mutex
  • ETIMEDOUT: abstime passed before cond arrived

This function causes the calling thread to lock mutex. It mutex cannot be locked, the thread is block until either the mutex is locked or abs_timeout is greater than CLOCK_REALTIME.

Example:

struct timespec abstime;clock_gettime(CLOCK_REALTIME, &abstime);abstime.tv_sec += 5; //time out after five secondsif ( pthread_mutex_timedlock(mutex, &abstime) == -1 ){     if ( errno == ETIMEDOUT ){          //Timedout     } else {          //Failed     }}

pthread_mutex_getprioceiling#

int pthread_mutex_getprioceiling(    pthread_mutex_t * mutex,    int * prioceiling)

Return: Zero on success or -1 with errno (see Errno) set to:

  • EINVAL: mutex or prioceiling is NULL

This function gets the mutex priority ceiling from mutex and stores it in prioceiling.

pthread_mutex_setprioceiling#

int pthread_mutex_setprioceiling(    pthread_mutex_t * mutex,    int prioceiling,    int * old_ceiling)

Return: Zero on success or -1 with errno (see Errno) set to:

  • EINVAL: mutex is NULL

This function sets mutex priority ceiling to prioceiling. If old_ceiling is not NULL, the old ceiling value is stored there.

pthread_mutex_init#

int pthread_mutex_init(    pthread_mutex_t * mutex,    const pthread_mutexattr_t * attr)

Return: Zero on success or -1 with errno (see Errno) set to:

  • EINVAL: mutex is NULL

This function initializes mutex with attr.

pthread_mutexattr_getprioceiling#

int pthread_mutexattr_getprioceiling(    const pthread_mutexattr_t * attr,    int * prioceiling)

Return: Zero on success or -1 with errno (see Errno) set to:

  • EINVAL: attr does not refer to an initialized mutex attribute object

This function gets the priority ceiling from attr and stores it in prioceiling.

pthread_mutexattr_setprioceiling#

int pthread_mutexattr_setprioceiling(    pthread_mutexattr_t * attr,    int prio_ceiling)

Return: Zero on success or -1 with errno (see Errno) set to:

  • EINVAL: attr does not refer to an initialized mutex attribute object

This function sets the priority ceiling in attr to prio_ceiling.

pthread_mutexattr_getprotocol#

int pthread_mutexattr_getprotocol(    const pthread_mutexattr_t * attr,    int * protocol)

Return: Zero on success or -1 with errno (see Errno) set to:

  • EINVAL: attr does not refer to an initialized mutex attribute object

This function gets the protocol from attr and stores it in protocol.

pthread_mutexattr_setprotocol#

int pthread_mutexattr_setprotocol(    pthread_mutexattr_t * attr,    int protocol)

Return: Zero on success or -1 with errno (see Errno) set to:

  • EINVAL: attr does not refer to an initialized mutex attribute object

This function sets protocol in attr to protocol.

pthread_mutexattr_getpshared#

int pthread_mutexattr_getpshared(    const pthread_mutexattr_t * attr,    int * pshared)

Return: Zero on success or -1 with errno (see Errno) set to:

  • EINVAL: attr does not refer to an initialized mutex attribute object

This function gets the process shared value from attr and stores it in pshared.

pthread_mutexattr_setpshared#

int pthread_mutexattr_setpshared(    pthread_mutexattr_t * attr,    int pshared)

Return: Zero on success or -1 with errno (see Errno) set to:

  • EINVAL: attr does not refer to an initialized mutex attribute object
  • EINVAL: pshared is not PTHREAD_PROCESS_SHARED or PTHREAD_PROCESS_PRIVATE

This function sets the process shared value in attr to pshared. A non-zero pshared means the mutex is shared.

pthread_mutexattr_gettype#

int pthread_mutexattr_gettype(    const pthread_mutexattr_t * attr,    int * type)

Return: Zero on success or -1 with errno (see Errno) set to:

  • EINVAL: attr does not refer to an initialized mutex attribute object

This function gets the type from attr and stores it in type.

pthread_mutexattr_settype#

int pthread_mutexattr_settype(    pthread_mutexattr_t * attr,    int type)

Return: Zero on success or -1 with errno (see Errno) set to:

  • EINVAL: attr does not refer to an initialized mutex attribute object

This function sets the type in attr to type. The type value should be on of:

  • PTHREAD_MUTEX_NORMAL
  • PTHREAD_MUTEX_RECURSIVE

pthread_mutexattr_init#

int pthread_mutexattr_init(    pthread_mutexattr_t * attr)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr is NULL

This function initializes attr with default values.

TodoThis should be a compile time define

pthread_mutexattr_destroy#

int pthread_mutexattr_destroy(    pthread_mutexattr_t * attr)

Return: Zero on success or -1 with errno set to:

  • EINVAL: attr is not an initialized mutex attribute object

This function destroys attr.

pthread_getschedparam#

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

Return: Zero on success or -1 with errno (see Errno) set to:

  • ESRCH: thread is not a valid
  • EINVAL: policy or param is NULL

This function gets thread's scheduling policy and scheduling parameters and stores them in policy and param respectively.

pthread_setschedparam#

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

Return: Zero on success or -1 with errno (see Errno) set to:

  • ESRCH: thread is not a valid
  • EINVAL: param is NULL or the priority is invalid

This function sets thread's scheduling policy and scheduling parameters to policy and param respectively.

pthread_self#

pthread_t pthread_self()

Return: The thread ID of the caller.

This function returns the thread ID of the calling process.


Updated on 18 September 2021 at 21:44:10 MDT