pthread_mutexattr_setprotocol(3P)

NAME
     pthread_mutexattr_setprotocol, pthread_mutexattr_getprotocol,
     pthread_mutexattr_setprioceiling, pthread_mutexattr_getprioceiling -
     set/get a mutex attribute object's priority and protocol

C SYNOPSIS
     #include <pthread.h>

     int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr,
          int protocol);

     int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *attr,
          int *oprotocol);

     int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr,
          int prioceiling);

     int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *attr,
          int *oprioceiling);

DESCRIPTION
     These functions manipulate a mutex attribute object referenced by attr
     which has been previously created by pthread_mutexattr_init().

     The function pthread_mutexattr_setprotocol() defines the thread priority
     protocol to be followed when acquiring and holding mutexes.  The protocol
     value may be one of PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT, or
     PTHREAD_PRIO_PROTECT.  The function pthread_mutexattr_getprotocol()
     stores into the memory referenced by oprotocol the thread priority
     protocol associated with the named mutex attribute object.  The default
     protocol is PTHREAD_PRIO_NONE.

     When a thread owns a mutex with the PTHREAD_PRIO_NONE protocol attribute,
     the thread's priority and scheduling are not affected by its mutex
     ownership.

     When a thread owns one or more mutexes that have been initialized with
     the PTHREAD_PRIO_PROTECT or PTHREAD_PRIO_INHERIT protocol, it will
     execute at the higher of its current priority or the highest priority
     associated with any owned mutex.

     For mutexes initialized with the PTHREAD_PRIO_INHERIT protocol, the
     priority associated with the owned mutex is the highest priority of any
     thread waiting to acquire the mutex.  (Note that if the thread that owns
     a mutex with the PTHREAD_PRIO_INHERIT protocol becomes blocked on another
     mutex with the PTHREAD_PRIO_INHERIT, protocol, priority inheritance will
     be propagated to the owning thread of this other mutex.)

     For mutexes initialized with the PTHREAD_PRIO_PROTECT protocol, the
     priority associated with the mutex is set either by calls to
     pthread_mutex_setprioceiling() or by call to
     pthread_mutexattr_setprioceiling() on the mutex attribute object that was
     used to initialized the mutex.  For pthread_mutexattr_setprioceiling(),
     the values of prioceiling must be within the values returned by
     sched_get_priority_min() and sched_get_priority_max() for the SCHED_FIFO
     policy.  The function pthread_mutexattr_getprioceiling() stores into the
     memory referenced by oprioceiling the priority associated with the named
     mutex attribute object; the default priority is the return value from
     sched_get_priority_min().  Note that a call to pthread_mutex_lock() will
     fail if the mutex protocol attribute is PTHREAD_PRIO_PROTECT and the
     priority associated with the mutex is less than the calling thread's
     priority.

     Priority inheritance is not supported for process-shared mutexes; all
     other protocols are supported, including priority ceiling.

DIAGNOSTICS
     All of the mutex attribute protocol functions return zero on success;
     otherwise, an error number is returned:

     [EINVAL]       The value specified by protocol or prioceiling is invalid.

     [EINVAL]       The value specified by protocol is PTHREAD_PRIO_INHERIT
                    and the process-shared attribute is set to
                    PTHREAD_PROCESS_SHARED.

SEE ALSO
     pthread_mutex_lock(3P), pthread_mutex_setprioceiling(3P),
     pthread_mutexattr_init(3P), sched_get_priority_min(3C),
     sched_get_priority_max(3C).