Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


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.

NetBSD 10.99                     June 12, 2016                    NetBSD 10.99