PTHREAD_MUTEXATTR(3)     BSD 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 -- mutex attribute
     operations

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 *attr, int *type);

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 dead-
            lock 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 unde-
            fined 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 unlock-
            ing done by pthread_cond_wait(3) and pthread_cond_timedwait(3).

       PTHREAD_MUTEX_DEFAULT
            Also this type of mutex will cause undefined behavior if reen-
            tered.  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 unde-
            fined behavior.  This is the default mutex type for
            pthread_mutexaddr_init().

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

     The pthread_mutexattr_set*() functions set the attribute that corresponds
     to each function name.

     The pthread_mutexattr_get*() functions copy the value of the attribute
     that corresponds to each function name to the location pointed to by the
     second function parameter.

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]           Out of memory.

     The pthread_mutexattr_destroy() function will fail if:

     [EINVAL]           Invalid value for attr.

     The pthread_mutexattr_setprioceiling() function will fail if:

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

     The pthread_mutexattr_getprioceiling() function will fail if:

     [EINVAL]           Invalid value for attr.

     The pthread_mutexattr_setprotocol() function will fail if:

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

     The pthread_mutexattr_getprotocol() function will fail if:

     [EINVAL]           Invalid value for attr.

     The pthread_mutexattr_settype() function shall fail if:

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

     The pthread_mutexattr_gettype() function will fail if:

     [EINVAL]           Invalid value for attr.

SEE ALSO
     pthread_mutex_init(3)

STANDARDS
     The pthread_mutexattr_init() and pthread_mutexattr_destroy() functions
     conform to ISO/IEC 9945-1:1996 (``POSIX.1'')

     The pthread_mutexattr_setprioceiling(),
     pthread_mutexattr_getprioceiling(), pthread_mutexattr_setprotocol(),
     pthread_mutexattr_getprotocol(), pthread_mutexattr_settype(), and
     pthread_mutexattr_gettype() functions conform to Version 2 of the Single
     UNIX Specification (``SUSv2'')

BSD                              July 9, 2010                              BSD