group::pthread

This is the interface for POSIX threads. Here is an example of creating a new thread:

#include <pthread.h>

void * thread_function(void * args);

pthread_t t;
pthread_attr_t attr;

if ( pthread_attr_init(&attr) < 0 ){
     perror("failed to initialize attr");
     return -1;
}

if ( pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED) < 0 ){
     perror("failed to set detach state");
     return -1;
}

if ( pthread_attr_setstacksize(&attr, 4096) < 0 ){
     perror("failed to set stack size");
     return -1;
}

if ( pthread_create(&t, &attr, thread_function, NULL) ){
     perror("failed to create thread");
     return -1;
}

Details

public intpthread_attr_getdetachstate(const pthread_attr_t * attr,int * detachstate)

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

Returns

Zero on success or -1 with errno set to:

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

public intpthread_attr_setdetachstate(pthread_attr_t * attr,int detachstate)

This function sets the detach state in attr with detachstate.

Returns

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

public intpthread_attr_getguardsize(const pthread_attr_t * attr,size_t * guardsize)

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

Returns

Zero on success or -1 with errno set to:

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

public intpthread_attr_setguardsize(pthread_attr_t * attr,size_t guardsize)

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

Returns

-1 with errno (see Errno) set to ENOTSUP


public intpthread_attr_getinheritsched(const pthread_attr_t * attr,int * inheritsched)

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

Returns

Zero on success or -1 with errno set to:

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

public intpthread_attr_setinheritsched(pthread_attr_t * attr,int inheritsched)

This function sets the inherit sched in attr with inheritsched.

Returns

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

public intpthread_attr_getschedparam(const pthread_attr_t * attr,struct sched_param * param)

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

Returns

Zero on success or -1 with errno set to:

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

public intpthread_attr_setschedparam(pthread_attr_t * attr,const struct sched_param * param)

This function sets the scheduling parameters in attr with param.

Returns

Zero on success or -1 with errno set to:

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

public intpthread_attr_getschedpolicy(const pthread_attr_t * attr,int * policy)

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

Returns

Zero on success or -1 with errno set to:

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

public intpthread_attr_setschedpolicy(pthread_attr_t * attr,int policy)

This function sets the scheduling policy in attr with policy.

Returns

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.

public intpthread_attr_getscope(const pthread_attr_t * attr,int * contentionscope)

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

Returns

Zero on success or -1 with errno set to:

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

public intpthread_attr_setscope(pthread_attr_t * attr,int contentionscope)

This function sets the contention scope in attr with contentionscope.

Returns

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

public intpthread_attr_getstacksize(const pthread_attr_t * attr,size_t * stacksize)

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

Returns

Zero on success or -1 with errno set to:

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

public intpthread_attr_setstacksize(pthread_attr_t * attr,size_t stacksize)

This function sets the stack size in attr with stacksize.

Returns

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

public intpthread_attr_getstackaddr(const pthread_attr_t * attr,void ** stackaddr)

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

Returns

Zero on success or -1 with errno set to:

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

public intpthread_attr_setstackaddr(pthread_attr_t * attr,void * stackaddr)

This function is not supported.

Returns

-1 with errno equal to ENOTSUP


public intpthread_attr_init(pthread_attr_t * attr)

This function initializes attr to the default values.

Returns

0 on success


public intpthread_attr_destroy(pthread_attr_t * attr)

Destroys the pthead attributes.

Parameters

  • attr A pointer to the attributes to destroy

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

Returns

0 on success or -1 and errno set to:

  • EINVAL: attr is NULL or uninitialized

public intpthread_cancel(pthread_t thread)

This function is not supported.

Returns

-1 with errno equal to ENOTSUP


public intpthread_setcancelstate(int state,int * oldstate)

This function is not supported.

Returns

-1 with errno equal to ENOTSUP


public intpthread_setcanceltype(int type,int * oldtype)

This function is not supported.

Returns

-1 with errno equal to ENOTSUP


public voidpthread_testcancel()


public intpthread_cond_init(pthread_cond_t * cond,const pthread_condattr_t * attr)

This function initializes a pthread block condition.

Returns

Zero on success or -1 with errno set to:

  • EINVAL: cond or attr is NULL

public intpthread_cond_destroy(pthread_cond_t * cond)

This function destroys a pthread block condition.

Returns

Zero on success or -1 with errno set to:

  • EINVAL: cond is NULL

public voidroot_cond_broadcast(void * args)


public intpthread_cond_broadcast(pthread_cond_t * cond)

This function wakes all threads that are blocked on cond.

Returns

Zero on success or -1 with errno set to:

  • EINVAL: cond is NULL or not initialized

public voidroot_cond_signal(void * args)


public intpthread_cond_signal(pthread_cond_t * cond)

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

Returns

Zero on success or -1 with errno set to:

  • EINVAL: cond is NULL or not initialized

public intpthread_cond_wait(pthread_cond_t * cond,pthread_mutex_t * mutex)

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

Returns

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

public intpthread_cond_timedwait(pthread_cond_t * cond,pthread_mutex_t * mutex,const struct timespec * abstime)

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 seconds
if ( pthread_cond_timedwait(cond, mutex, &abstime) == -1 ){
     if ( errno == ETIMEDOUT ){
          //Timedout
     } else {
          //Failed
     }
}

Returns

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

public intpthread_condattr_init(pthread_condattr_t * attr)

This function initializes attr with the default values.

Returns

Zero on success or -1 with errno set to:

  • EINVAL: attr is NULL

public intpthread_condattr_destroy(pthread_condattr_t * attr)

This function destroys attr.

Returns

Zero on success or -1 with errno set to:

  • EINVAL: attr is not an initialized condition attribute

public intpthread_condattr_getpshared(const pthread_condattr_t * attr,int * pshared)

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

Returns

Zero on success or -1 with errno set to:

  • EINVAL: attr is not an initialized condition attribute

public intpthread_condattr_setpshared(pthread_condattr_t * attr,int pshared)

This function sets the pshared value in attr to pshared.

Returns

Zero on success or -1 with errno set to:

  • EINVAL: attr is not an initialized condition attribute

public intpthread_condattr_getclock(const pthread_condattr_t * attr,clockid_t * clock_id)

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

Returns

Zero on success or -1 with errno set to:

  • EINVAL: attr is not an initialized condition attribute

public intpthread_condattr_setclock(pthread_condattr_t * attr,clockid_t clock_id)

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

Returns

Zero on success or -1 with errno set to:

  • ENOTSUP: this function is not supported

public intpthread_create(pthread_t * thread,const pthread_attr_t * attr,void *(*)(void *) start_routine,void * arg)

This function creates a new thread.

Returns

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

public intpthread_join(pthread_t thread,void ** value_ptr)

This function blocks the calling thread until thread terminates.

Returns

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.

public intpthread_mutex_lock(pthread_mutex_t * mutex)

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

Returns

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

public intpthread_mutex_trylock(pthread_mutex_t * mutex)

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

Returns

Zero on success or -1 with errno set to:

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

public intpthread_mutex_unlock(pthread_mutex_t * mutex)

This function unlocks mutex.

Returns

Zero on success or -1 with errno set to:

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

public intpthread_mutex_destroy(pthread_mutex_t * mutex)

This function destroys mutex.

Returns

Zero on success or -1 with errno set to:

  • EINVAL: mutex is NULL

public intpthread_mutex_timedlock(pthread_mutex_t * mutex,const struct timespec * abs_timeout)

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 seconds
if ( pthread_mutex_timedlock(mutex, &abstime) == -1 ){
     if ( errno == ETIMEDOUT ){
          //Timedout
     } else {
          //Failed
     }
}

Returns

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

public intpthread_mutex_getprioceiling(pthread_mutex_t * mutex,int * prioceiling)

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

Returns

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

  • EINVAL: mutex or prioceiling is NULL

public intpthread_mutex_setprioceiling(pthread_mutex_t * mutex,int prioceiling,int * old_ceiling)

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

Returns

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

  • EINVAL: mutex is NULL

public intpthread_mutex_init(pthread_mutex_t * mutex,const pthread_mutexattr_t * attr)

This function initializes mutex with attr.

Returns

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

  • EINVAL: mutex is NULL

public intpthread_mutexattr_getprioceiling(const pthread_mutexattr_t * attr,int * prioceiling)

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

Returns

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

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

public intpthread_mutexattr_setprioceiling(pthread_mutexattr_t * attr,int prio_ceiling)

This function sets the priority ceiling in attr to prio_ceiling.

Returns

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

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

public intpthread_mutexattr_getprotocol(const pthread_mutexattr_t * attr,int * protocol)

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

Returns

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

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

public intpthread_mutexattr_setprotocol(pthread_mutexattr_t * attr,int protocol)

This function sets protocol in attr to protocol.

Returns

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

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

public intpthread_mutexattr_getpshared(const pthread_mutexattr_t * attr,int * pshared)

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

Returns

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

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

public intpthread_mutexattr_setpshared(pthread_mutexattr_t * attr,int pshared)

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

Returns

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

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

public intpthread_mutexattr_gettype(const pthread_mutexattr_t * attr,int * type)

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

Returns

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

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

public intpthread_mutexattr_settype(pthread_mutexattr_t * attr,int type)

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

  • PTHREAD_MUTEX_NORMAL
  • PTHREAD_MUTEX_RECURSIVE

Returns

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

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

public intpthread_mutexattr_init(pthread_mutexattr_t * attr)

This function initializes attr with default values.

Returns

Zero on success or -1 with errno set to:

  • EINVAL: attr is NULL

public intpthread_mutexattr_destroy(pthread_mutexattr_t * attr)

This function destroys attr.

Returns

Zero on success or -1 with errno set to:

  • EINVAL: attr is not an initialized mutex attribute object

public intpthread_getschedparam(pthread_t thread,int * policy,struct sched_param * param)

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

Returns

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

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

public intpthread_setschedparam(pthread_t thread,int policy,struct sched_param * param)

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

Returns

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

public pthread_tpthread_self()

This function returns the thread ID of the calling process.

Returns

The thread ID of the caller.


X

Thanks for Coming!

Subscribe to news and updates