PTHREAD_MUTEXATTR(3)

PTHREAD_MUTEXATTR(3) | Library Functions Manual | PTHREAD_MUTEXATTR(3)

# NAME

`pthread_mutexattr_init`, `pthread_mutexattr_destroy`, `pthread_mutexattr_setprioceiling`, `pthread_mutexattr_getprioceiling`, `pthread_mutexattr_setprotocol`, `pthread_mutexattr_getprotocol`, `pthread_mutexattr_settype`, `pthread_mutexattr_gettype`, `pthread_mutexattr_getpshared`, `pthread_mutexattr_setpshared` —
mutex attribute operations

# LIBRARY

POSIX Threads Library (libpthread, -lpthread)

# SYNOPSIS

`#include <pthread.h>`

int
`pthread_mutexattr_init`(pthread_mutexattr_t *attr);

int
`pthread_mutexattr_destroy`(pthread_mutexattr_t *attr);

int
`pthread_mutexattr_setprioceiling`(pthread_mutexattr_t *attr, int prioceiling);

int
`pthread_mutexattr_getprioceiling`(pthread_mutexattr_t *attr, int *prioceiling);

int
`pthread_mutexattr_setprotocol`(pthread_mutexattr_t *attr, int protocol);

int
`pthread_mutexattr_getprotocol`(pthread_mutexattr_t *attr, int *protocol);

int
`pthread_mutexattr_settype`(pthread_mutexattr_t *attr, int type);

int
`pthread_mutexattr_gettype`(pthread_mutexattr_t * restrict attr, int * restrict type);

int
`pthread_mutexattr_getpshared`(const pthread_mutexattr_t * __restrict attr, int * __restrict pshared);

int
`pthread_mutexattr_setpshared`(pthread_mutexattr_t * attr, int pshared);

# DESCRIPTION

Mutex attributes are used to specify parameters to `pthread_mutex_init`(). Like with thread attributes, one attribute object can be used in multiple calls to pthread_mutex_init(3), with or without modifications between calls.

The `pthread_mutexattr_init`() function initializes attr with all the default mutex attributes.

The `pthread_mutexattr_destroy`() function destroys attr.

The `pthread_mutexattr_settype`() functions set the mutex type value of the attribute. Valid mutex types are:

`PTHREAD_MUTEX_NORMAL`
  This type of mutex does not check for usage errors. It will deadlock if reentered, and result in undefined behavior if a locked mutex is unlocked by another thread. Attempts to unlock an already unlocked `PTHREAD_MUTEX_NORMAL` mutex will result in undefined behavior.
`PTHREAD_MUTEX_ERRORCHECK`
  These mutexes do check for usage errors. If an attempt is made to relock a `PTHREAD_MUTEX_ERRORCHECK` mutex without first dropping the lock, an error will be returned. If a thread attempts to unlock a `PTHREAD_MUTEX_ERRORCHECK` mutex that is locked by another thread, an error will be returned. If a thread attempts to unlock a `PTHREAD_MUTEX_ERRORCHECK` thread that is unlocked, an error will be returned.
`PTHREAD_MUTEX_RECURSIVE`
  These mutexes allow recursive locking. An attempt to relock a `PTHREAD_MUTEX_RECURSIVE` mutex that is already locked by the same thread succeeds. An equivalent number of pthread_mutex_unlock(3) calls are needed before the mutex will wake another thread waiting on this lock. If a thread attempts to unlock a `PTHREAD_MUTEX_RECURSIVE` mutex that is locked by another thread, an error will be returned. If a thread attempts to unlock a `PTHREAD_MUTEX_RECURSIVE` thread that is unlocked, an error will be returned.

  It is advised that `PTHREAD_MUTEX_RECURSIVE` mutexes are not used with condition variables. This is because of the implicit unlocking done by pthread_cond_wait(3) and pthread_cond_timedwait(3).

`PTHREAD_MUTEX_DEFAULT`
  Also this type of mutex will cause undefined behavior if reentered. Unlocking a `PTHREAD_MUTEX_DEFAULT` mutex locked by another thread will result in undefined behavior. Attempts to unlock an already unlocked `PTHREAD_MUTEX_DEFAULT` mutex will result in undefined behavior.

  This is the default mutex type for `pthread_mutexattr_init`().

The `pthread_mutexattr_gettype`() functions copy the type value of the attribute to the location pointed to by the second parameter.

The `pthread_mutexattr_getpshared`() function obtains the value of the process-shared attribute from the attributes object referenced by attr.

The `pthread_mutexattr_setpshared`() function is used to set the process-shared attribute in an initialised attributes object referenced by attr.

The `pthread_mutexattr_getprotocol`() and `pthread_mutexattr_setprotocol`() functions shall get and set the protocol attribute of a mutex attributes object pointed to by attr which was previously created by the function `pthread_mutexattr_init`().

The `pthread_mutexattr_getprioceiling`() and `pthread_mutexattr_setprioceiling`() functions, shall get and set the priority ceiling attribute of a mutex attributes object pointed to by attr which was previously created by the function `pthread_mutexattr_init`().

# RETURN VALUES

If successful, these functions return 0. Otherwise, an error number is returned to indicate the error.

# ERRORS

The `pthread_mutexattr_init`() function shall fail if:

[`ENOMEM`]
  Insufficient memory exists to initialize the mutex attributes object.

The `pthread_mutexattr_settype`() function shall fail if:

[`EINVAL`]
  The value specified either by type or attr is invalid.

No error numbers are defined for the `pthread_mutexattr_destroy`() and `pthread_mutexattr_gettype`() functions.

`pthread_mutexattr_setprioceiling`() may fail if:

[`EINVAL`]
  Invalid value for attr, or invalid value for prioceiling.

`pthread_mutexattr_getprioceiling`() may fail if:

[`EINVAL`]
  Invalid value for attr.

`pthread_mutexattr_setprotocol`() may fail if:

[`EINVAL`]
  Invalid value for attr, or invalid value for protocol.

`pthread_mutexattr_getprotocol`() may fail if:

[`EINVAL`]
  Invalid value for attr.

`pthread_mutexattr_getpshared`() and `pthread_mutexattr_setpshared`() may fail if:

[`EINVAL`]
  the value specified by attr is invalid.

# SEE ALSO

pthread_mutex_init(3)

# STANDARDS

These functions conform to IEEE Std 1003.1-2001 (“POSIX.1”).

# BUGS

The `pthread_mutexattr_getpshared`() and `pthread_mutexattr_setpshared`() functions are hidden by default since only thread shared attributes are supported.

June 12, 2016 | NetBSD 9.0