1PTHREAD_MUTEXATTR_GETPROTOCOPLO(SPI)X Programmer's MPaTnHuRaElAD_MUTEXATTR_GETPROTOCOL(P)
2
3
4

NAME

6       pthread_mutexattr_getprotocol,  pthread_mutexattr_setprotocol - get and
7       set the protocol attribute of the  mutex  attributes  object  (REALTIME
8       THREADS)
9

SYNOPSIS

11       #include <pthread.h>
12
13       int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *
14              restrict attr, int *restrict protocol);
15       int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr,
16              int protocol);
17
18
19
20

DESCRIPTION

22       The pthread_mutexattr_getprotocol() and pthread_mutexattr_setprotocol()
23       functions, respectively, shall get and set the protocol attribute of  a
24       mutex attributes object pointed to by attr which was previously created
25       by the function pthread_mutexattr_init().
26
27       The protocol attribute defines the protocol to be followed in utilizing
28       mutexes. The value of protocol may be one of:
29
30       PTHREAD_PRIO_NONE
31
32       PTHREAD_PRIO_INHERIT
33
34
35       PTHREAD_PRIO_PROTECT
36
37
38       which are defined in the <pthread.h> header.
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 mutexes with the PTHREAD_PRIO_INHERIT  protocol  attribute,  it
46       shall  execute  at  the  higher  of its priority or the priority of the
47       highest priority thread waiting on any of the  mutexes  owned  by  this
48       thread and initialized with this protocol.
49
50       When   a   thread  owns  one  or  more  mutexes  initialized  with  the
51       PTHREAD_PRIO_PROTECT protocol, it shall execute at the  higher  of  its
52       priority  or  the  highest  of the priority ceilings of all the mutexes
53       owned by this thread and initialized with this attribute, regardless of
54       whether other threads are blocked on any of these mutexes or not.
55
56       While  a  thread is holding a mutex which has been initialized with the
57       PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT  protocol  attributes,  it
58       shall not be subject to being moved to the tail of the scheduling queue
59       at its priority in the event that its  original  priority  is  changed,
60       such as by a call to sched_setparam().  Likewise, when a thread unlocks
61       a mutex that has been  initialized  with  the  PTHREAD_PRIO_INHERIT  or
62       PTHREAD_PRIO_PROTECT  protocol  attributes,  it shall not be subject to
63       being moved to the tail of the scheduling queue at its priority in  the
64       event that its original priority is changed.
65
66       If  a  thread simultaneously owns several mutexes initialized with dif‐
67       ferent protocols, it shall execute at the  highest  of  the  priorities
68       that it would have obtained by each of these protocols.
69
70       When  a thread makes a call to pthread_mutex_lock(), the mutex was ini‐
71       tialized   with   the   protocol    attribute    having    the    value
72       PTHREAD_PRIO_INHERIT,  when  the  calling thread is blocked because the
73       mutex is owned by another thread, that owner thread shall  inherit  the
74       priority level of the calling thread as long as it continues to own the
75       mutex. The implementation shall update its execution  priority  to  the
76       maximum of its assigned priority and all its inherited priorities. Fur‐
77       thermore, if this owner thread itself becomes blocked on another mutex,
78       the  same priority inheritance effect shall be propagated to this other
79       owner thread, in a recursive manner.
80

RETURN VALUE

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

ERRORS

87       The pthread_mutexattr_setprotocol() function shall fail if:
88
89       ENOTSUP
90              The value specified by protocol is an unsupported value.
91
92
93       The pthread_mutexattr_getprotocol() and pthread_mutexattr_setprotocol()
94       functions may fail if:
95
96       EINVAL The value specified by attr or protocol is invalid.
97
98       EPERM  The caller does not have the privilege to perform the operation.
99
100
101       These functions shall not return an error code of [EINTR].
102
103       The following sections are informative.
104

EXAMPLES

106       None.
107

APPLICATION USAGE

109       None.
110

RATIONALE

112       None.
113

FUTURE DIRECTIONS

115       None.
116

SEE ALSO

118       pthread_cond_destroy()  ,  pthread_create() , pthread_mutex_destroy() ,
119       the Base Definitions volume of IEEE Std 1003.1-2001, <pthread.h>
120

COPYRIGHT

122       Portions of this text are reprinted and reproduced in  electronic  form
123       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
124       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
125       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
126       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
127       event of any discrepancy between this version and the original IEEE and
128       The Open Group Standard, the original IEEE and The Open Group  Standard
129       is  the  referee document. The original Standard can be obtained online
130       at http://www.opengroup.org/unix/online.html .
131
132
133
134IEEE/The Open Group                  2003     PTHREAD_MUTEXATTR_GETPROTOCOL(P)