PROLOG | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

PTHREAD_MUTEXATTR_GETPROTOCOL(3P)rogrammer'sTManualMUTEXATTR_GETPROTOCOL(3P)

PROLOG         top

       This manual page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the
       corresponding Linux manual page for details of Linux behavior), or
       the interface may not be implemented on Linux.

NAME         top

       pthread_mutexattr_getprotocol, pthread_mutexattr_setprotocol — get
       and set the protocol attribute of the mutex attributes object
       (REALTIME THREADS)

SYNOPSIS         top

       #include <pthread.h>

       int pthread_mutexattr_getprotocol(const pthread_mutexattr_t
           *restrict attr, int *restrict protocol);
       int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr,
           int protocol);

DESCRIPTION         top

       The pthread_mutexattr_getprotocol() and
       pthread_mutexattr_setprotocol() functions, respectively, 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 protocol attribute defines the protocol to be followed in
       utilizing mutexes.  The value of protocol may be one of:

       PTHREAD_PRIO_INHERIT
       PTHREAD_PRIO_NONE
       PTHREAD_PRIO_PROTECT

       which are defined in the <pthread.h> header. The default value of the
       attribute shall be PTHREAD_PRIO_NONE.

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

       When a thread is blocking higher priority threads because of owning
       one or more robust mutexes with the PTHREAD_PRIO_INHERIT protocol
       attribute, it shall execute at the higher of its priority or the
       priority of the highest priority thread waiting on any of the robust
       mutexes owned by this thread and initialized with this protocol.

       When a thread is blocking higher priority threads because of owning
       one or more non-robust mutexes with the PTHREAD_PRIO_INHERIT protocol
       attribute, it shall execute at the higher of its priority or the
       priority of the highest priority thread waiting on any of the non-
       robust mutexes owned by this thread and initialized with this
       protocol.

       When a thread owns one or more robust mutexes initialized with the
       PTHREAD_PRIO_PROTECT protocol, it shall execute at the higher of its
       priority or the highest of the priority ceilings of all the robust
       mutexes owned by this thread and initialized with this attribute,
       regardless of whether other threads are blocked on any of these
       robust mutexes or not.

       When a thread owns one or more non-robust mutexes initialized with
       the PTHREAD_PRIO_PROTECT protocol, it shall execute at the higher of
       its priority or the highest of the priority ceilings of all the non-
       robust mutexes owned by this thread and initialized with this
       attribute, regardless of whether other threads are blocked on any of
       these non-robust mutexes or not.

       While a thread is holding a mutex which has been initialized with the
       PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT protocol attributes, it
       shall not be subject to being moved to the tail of the scheduling
       queue at its priority in the event that its original priority is
       changed, such as by a call to sched_setparam().  Likewise, when a
       thread unlocks a mutex that has been initialized with the
       PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT protocol attributes, it
       shall not be subject to being moved to the tail of the scheduling
       queue at its priority in the event that its original priority is
       changed.

       If a thread simultaneously owns several mutexes initialized with
       different protocols, it shall execute at the highest of the
       priorities that it would have obtained by each of these protocols.

       When a thread makes a call to pthread_mutex_lock(), the mutex was
       initialized with the protocol attribute having the value
       PTHREAD_PRIO_INHERIT, when the calling thread is blocked because the
       mutex is owned by another thread, that owner thread shall inherit the
       priority level of the calling thread as long as it continues to own
       the mutex. The implementation shall update its execution priority to
       the maximum of its assigned priority and all its inherited
       priorities.  Furthermore, if this owner thread itself becomes blocked
       on another mutex with the protocol attribute having the value
       PTHREAD_PRIO_INHERIT, the same priority inheritance effect shall be
       propagated to this other owner thread, in a recursive manner.

       The behavior is undefined if the value specified by the attr argument
       to pthread_mutexattr_getprotocol() or pthread_mutexattr_setprotocol()
       does not refer to an initialized mutex attributes object.

RETURN VALUE         top

       Upon successful completion, the pthread_mutexattr_getprotocol() and
       pthread_mutexattr_setprotocol() functions shall return zero;
       otherwise, an error number shall be returned to indicate the error.

ERRORS         top

       The pthread_mutexattr_setprotocol() function shall fail if:

       ENOTSUP
              The value specified by protocol is an unsupported value.

       The pthread_mutexattr_getprotocol() and
       pthread_mutexattr_setprotocol() functions may fail if:

       EINVAL The value specified by protocol is invalid.

       EPERM  The caller does not have the privilege to perform the
              operation.

       These functions shall not return an error code of [EINTR].

       The following sections are informative.

EXAMPLES         top

       None.

APPLICATION USAGE         top

       None.

RATIONALE         top

       If an implementation detects that the value specified by the attr
       argument to pthread_mutexattr_getprotocol() or
       pthread_mutexattr_setprotocol() does not refer to an initialized
       mutex attributes object, it is recommended that the function should
       fail and report an [EINVAL] error.

FUTURE DIRECTIONS         top

       None.

SEE ALSO         top

       pthread_cond_destroy(3p), pthread_create(3p),
       pthread_mutex_destroy(3p)

       The Base Definitions volume of POSIX.1‐2008, pthread.h(0p)

COPYRIGHT         top

       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information
       Technology -- Portable Operating System Interface (POSIX), The Open
       Group Base Specifications Issue 7, Copyright (C) 2013 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1
       applied.) In the event of any discrepancy between this version and
       the original IEEE and The Open Group Standard, the original IEEE and
       The Open Group Standard is the referee document. The original
       Standard can be obtained online at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the
       source files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group                 2013   PTHREAD_MUTEXATTR_GETPROTOCOL(3P)

Pages that refer to this page: pthread.h(0p)pthread_mutexattr_setprotocol(3p)