pthread_mutexattr(3) - NetBSD Manual Pages

PTHREAD_MUTEXATTR(3)    NetBSD 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 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_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 pri-
     ority 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 9.1                       June 12, 2016                      NetBSD 9.1