PTHREAD_MUTEXATTR_GETPROTOCOPLO(S3I)X Programmer's MPaTnHuRaElAD_MUTEXATTR_GETPROTOCOL(3)



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

NNAAMMEE
       pthread_mutexattr_getprotocol, pthread_mutexattr_setprotocol -- get and
       set the protocol attribute of the mutex attributes object (RREEAALLTTIIMMEE
       TTHHRREEAADDSS)

SSYYNNOOPPSSIISS
       #include <pthread.h>

       int pthread_mutexattr_getprotocol(const pthread_mutexattr_t
           *restrict _a_t_t_r, int *restrict _p_r_o_t_o_c_o_l);
       int pthread_mutexattr_setprotocol(pthread_mutexattr_t *_a_t_t_r,
           int _p_r_o_t_o_c_o_l);

DDEESSCCRRIIPPTTIIOONN
       The _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___g_e_t_p_r_o_t_o_c_o_l() and _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___s_e_t_p_r_o_t_o_c_o_l()
       functions, respectively, shall get and set the protocol attribute of a
       mutex attributes object pointed to by _a_t_t_r which was previously created
       by the function _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___i_n_i_t().

       The _p_r_o_t_o_c_o_l attribute defines the protocol to be followed in utilizing
       mutexes.  The value of _p_r_o_t_o_c_o_l may be one of:

       PTHREAD_PRIO_INHERIT
       PTHREAD_PRIO_NONE
       PTHREAD_PRIO_PROTECT

       which are defined in the _<_p_t_h_r_e_a_d_._h_> header. The default value of the
       attribute shall be PTHREAD_PRIO_NONE.

       When a thread owns a mutex with the PTHREAD_PRIO_NONE _p_r_o_t_o_c_o_l
       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 _p_r_o_t_o_c_o_l
       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 _p_r_o_t_o_c_o_l
       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 _s_c_h_e_d___s_e_t_p_a_r_a_m().  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 _p_t_h_r_e_a_d___m_u_t_e_x___l_o_c_k(), 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 _p_r_o_t_o_c_o_l 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 _a_t_t_r argument
       to _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___g_e_t_p_r_o_t_o_c_o_l() or _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___s_e_t_p_r_o_t_o_c_o_l()
       does not refer to an initialized mutex attributes object.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, the _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___g_e_t_p_r_o_t_o_c_o_l() and
       _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___s_e_t_p_r_o_t_o_c_o_l() functions shall return zero; otherwise,
       an error number shall be returned to indicate the error.

EERRRROORRSS
       The _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___s_e_t_p_r_o_t_o_c_o_l() function shall fail if:

       EENNOOTTSSUUPP
              The value specified by _p_r_o_t_o_c_o_l is an unsupported value.

       The _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___g_e_t_p_r_o_t_o_c_o_l() and _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___s_e_t_p_r_o_t_o_c_o_l()
       functions may fail if:

       EEIINNVVAALL The value specified by _p_r_o_t_o_c_o_l is invalid.

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

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

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

RRAATTIIOONNAALLEE
       If an implementation detects that the value specified by the _a_t_t_r
       argument to _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___g_e_t_p_r_o_t_o_c_o_l() or
       _p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r___s_e_t_p_r_o_t_o_c_o_l() does not refer to an initialized mutex
       attributes object, it is recommended that the function should fail and
       report an [[EEIINNVVAALL]] error.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _p_t_h_r_e_a_d___c_o_n_d___d_e_s_t_r_o_y(), _p_t_h_r_e_a_d___c_r_e_a_t_e(), _p_t_h_r_e_a_d___m_u_t_e_x___d_e_s_t_r_o_y()

       The Base Definitions volume of POSIX.1-2017, <<pptthhrreeaadd..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  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.opengroup.org/unix/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                  2017     PTHREAD_MUTEXATTR_GETPROTOCOL(3)
