1PTHREAD_MUTEXATTR_GETPROTOCOPLO(S3IPX)Programmer'sPMTaHnRuEaAlD_MUTEXATTR_GETPROTOCOL(3P)
2
3
4

PROLOG

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

NAME

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

SYNOPSIS

17       #include <pthread.h>
18
19       int pthread_mutexattr_getprotocol(const pthread_mutexattr_t
20           *restrict attr, int *restrict protocol);
21       int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr,
22           int protocol);
23

DESCRIPTION

25       The pthread_mutexattr_getprotocol() and pthread_mutexattr_setprotocol()
26       functions,  respectively, shall get and set the protocol attribute of a
27       mutex attributes object pointed to by attr which was previously created
28       by the function pthread_mutexattr_init().
29
30       The protocol attribute defines the protocol to be followed in utilizing
31       mutexes.  The value of protocol may be one of:
32
33       PTHREAD_PRIO_INHERIT
34       PTHREAD_PRIO_NONE
35       PTHREAD_PRIO_PROTECT
36
37       which are defined in the <pthread.h> header. The default value  of  the
38       attribute shall be PTHREAD_PRIO_NONE.
39
40       When  a  thread  owns  a  mutex  with  the  PTHREAD_PRIO_NONE  protocol
41       attribute, its priority and scheduling shall not  be  affected  by  its
42       mutex ownership.
43
44       When a thread is blocking higher priority threads because of owning one
45       or  more  robust  mutexes  with   the   PTHREAD_PRIO_INHERIT   protocol
46       attribute, it shall execute at the higher of its priority or the prior‐
47       ity of the highest priority thread waiting on any of the robust mutexes
48       owned by this thread and initialized with this protocol.
49
50       When a thread is blocking higher priority threads because of owning one
51       or more  non-robust  mutexes  with  the  PTHREAD_PRIO_INHERIT  protocol
52       attribute, it shall execute at the higher of its priority or the prior‐
53       ity of the highest priority thread waiting on  any  of  the  non-robust
54       mutexes owned by this thread and initialized with this protocol.
55
56       When  a  thread  owns  one  or more robust mutexes initialized with the
57       PTHREAD_PRIO_PROTECT protocol, it shall execute at the  higher  of  its
58       priority  or  the  highest  of  the priority ceilings of all the robust
59       mutexes owned by this  thread  and  initialized  with  this  attribute,
60       regardless  of whether other threads are blocked on any of these robust
61       mutexes or not.
62
63       When a thread owns one or more non-robust mutexes initialized with  the
64       PTHREAD_PRIO_PROTECT  protocol,  it  shall execute at the higher of its
65       priority or the highest of the priority ceilings of all the  non-robust
66       mutexes  owned  by  this  thread  and  initialized with this attribute,
67       regardless of whether other threads are blocked on any  of  these  non-
68       robust mutexes or not.
69
70       While  a  thread is holding a mutex which has been initialized with the
71       PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT  protocol  attributes,  it
72       shall not be subject to being moved to the tail of the scheduling queue
73       at its priority in the event that its  original  priority  is  changed,
74       such as by a call to sched_setparam().  Likewise, when a thread unlocks
75       a mutex that has been  initialized  with  the  PTHREAD_PRIO_INHERIT  or
76       PTHREAD_PRIO_PROTECT  protocol  attributes,  it shall not be subject to
77       being moved to the tail of the scheduling queue at its priority in  the
78       event that its original priority is changed.
79
80       If  a  thread simultaneously owns several mutexes initialized with dif‐
81       ferent protocols, it shall execute at the  highest  of  the  priorities
82       that it would have obtained by each of these protocols.
83
84       When  a thread makes a call to pthread_mutex_lock(), the mutex was ini‐
85       tialized   with   the   protocol    attribute    having    the    value
86       PTHREAD_PRIO_INHERIT,  when  the  calling thread is blocked because the
87       mutex is owned by another thread, that owner thread shall  inherit  the
88       priority level of the calling thread as long as it continues to own the
89       mutex. The implementation shall update its execution  priority  to  the
90       maximum  of  its  assigned  priority  and all its inherited priorities.
91       Furthermore, if this owner thread itself  becomes  blocked  on  another
92       mutex    with    the    protocol    attribute    having    the    value
93       PTHREAD_PRIO_INHERIT, the same priority  inheritance  effect  shall  be
94       propagated to this other owner thread, in a recursive manner.
95
96       The  behavior  is undefined if the value specified by the attr argument
97       to pthread_mutexattr_getprotocol()  or  pthread_mutexattr_setprotocol()
98       does not refer to an initialized mutex attributes object.
99

RETURN VALUE

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

ERRORS

106       The pthread_mutexattr_setprotocol() function shall fail if:
107
108       ENOTSUP
109              The value specified by protocol is an unsupported value.
110
111       The pthread_mutexattr_getprotocol() and pthread_mutexattr_setprotocol()
112       functions may fail if:
113
114       EINVAL The value specified by protocol is invalid.
115
116       EPERM  The caller does not have the privilege to perform the operation.
117
118       These functions shall not return an error code of [EINTR].
119
120       The following sections are informative.
121

EXAMPLES

123       None.
124

APPLICATION USAGE

126       None.
127

RATIONALE

129       If an implementation detects that the value specified by the attr argu‐
130       ment  to pthread_mutexattr_getprotocol() or pthread_mutexattr_setproto‐
131       col() does not refer to an initialized mutex attributes object,  it  is
132       recommended that the function should fail and report an [EINVAL] error.
133

FUTURE DIRECTIONS

135       None.
136

SEE ALSO

138       pthread_cond_destroy(), pthread_create(), pthread_mutex_destroy()
139
140       The Base Definitions volume of POSIX.1‐2017, <pthread.h>
141
143       Portions  of  this text are reprinted and reproduced in electronic form
144       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
145       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
146       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
147       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
148       event of any discrepancy between this version and the original IEEE and
149       The  Open Group Standard, the original IEEE and The Open Group Standard
150       is the referee document. The original Standard can be  obtained  online
151       at http://www.opengroup.org/unix/online.html .
152
153       Any  typographical  or  formatting  errors that appear in this page are
154       most likely to have been introduced during the conversion of the source
155       files  to  man page format. To report such errors, see https://www.ker
156       nel.org/doc/man-pages/reporting_bugs.html .
157
158
159
160IEEE/The Open Group                  2017    PTHREAD_MUTEXATTR_GETPROTOCOL(3P)
Impressum