January 30, 2003 PTHREAD_MUTEXATTR 3

### NAME

pthread_mutexattr_init, pthread_mutexattr_destroy, pthread_mutexattr_settype, pthread_mutexattr_gettype - mutex attribute operations

### LIBRARY

POSIX Thread Library (libpthread, -lpthread)

### SYNOPSIS

```int` pthread_mutexattr_init(```pthread_mutexattr_t *attr`)
```int` pthread_mutexattr_destroy(```pthread_mutexattr_t *attr`)
```int` pthread_mutexattr_settype(```pthread_mutexattr_t *attr``, int type`)
```int` pthread_mutexattr_gettype(```pthread_mutexattr_t * restrict attr``, int * restrict type`)

### DESCRIPTION

Mutex attributes are used to specify parameters to pthread_mutex_init(``). One attribute object can be used in multiple calls to pthread_mutex_init(``), 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`, ```PTHREAD_MUTEX_ERRORCHECK`, ```PTHREAD_MUTEX_RECURSIVE`, and ```PTHREAD_MUTEX_DEFAULT`. The default mutex type for pthread_mutexaddr_init(``) is ```PTHREAD_MUTEX_DEFAULT`.

```PTHREAD_MUTEX_NORMAL` mutexes do not check for usage errors. ```PTHREAD_MUTEX_NORMAL` mutexes 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` 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` 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.

```PTHREAD_MUTEX_DEFAULT` mutexes result in 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.

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

### RETURN VALUES

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

### ERRORS

pthread_mutexattr_init(``) shall fail if:

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

pthread_mutexattr_settype(``) shall fail if:

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

pthread_mutexattr_destroy(``), pthread_mutexattr_settype(``), and pthread_mutexattr_gettype(``) may fail if:

[```EINVAL`]
  Invalid value for ```attr`.

### SEE ALSO

pthread_mutex_init(3)

### STANDARDS

pthread_mutexattr_init(``), pthread_mutexattr_destroy(``), pthread_mutexattr_settype(``), and pthread_mutexattr_gettype(``) conform to ISO/IEC 9945-1:1996 (``POSIX.1'') .