1PTHREAD_MUTEX_LOCK(3P)     POSIX Programmer's Manual    PTHREAD_MUTEX_LOCK(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_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock —  lock
13       and unlock a mutex
14

SYNOPSIS

16       #include <pthread.h>
17
18       int pthread_mutex_lock(pthread_mutex_t *mutex);
19       int pthread_mutex_trylock(pthread_mutex_t *mutex);
20       int pthread_mutex_unlock(pthread_mutex_t *mutex);
21

DESCRIPTION

23       The  mutex  object  referenced  by  mutex  shall be locked by a call to
24       pthread_mutex_lock() that returns zero or [EOWNERDEAD].  If  the  mutex
25       is  already  locked  by  another thread, the calling thread shall block
26       until the mutex becomes available. This operation shall return with the
27       mutex  object  referenced by mutex in the locked state with the calling
28       thread as its owner. If a thread attempts to relock a mutex that it has
29       already  locked,  pthread_mutex_lock() shall behave as described in the
30       Relock column of the following table. If a thread attempts to unlock  a
31       mutex   that   it  has  not  locked  or  a  mutex  which  is  unlocked,
32       pthread_mutex_unlock() shall behave as described in the Unlock When Not
33       Owner column of the following table.
34
35         ┌───────────┬────────────┬────────────────┬───────────────────────┐
36Mutex Type Robustness Relock     Unlock When Not Owner 
37         ├───────────┼────────────┼────────────────┼───────────────────────┤
38         │NORMAL     │ non-robust │ deadlock       │ undefined behavior    │
39         ├───────────┼────────────┼────────────────┼───────────────────────┤
40         │NORMAL     │ robust     │ deadlock       │ error returned        │
41         ├───────────┼────────────┼────────────────┼───────────────────────┤
42         │ERRORCHECK │ either     │ error returned │ error returned        │
43         ├───────────┼────────────┼────────────────┼───────────────────────┤
44         │RECURSIVE  │ either     │ recursive      │ error returned        │
45         │           │            │ (see below)    │                       │
46         ├───────────┼────────────┼────────────────┼───────────────────────┤
47         │DEFAULT    │ non-robust │ undefined      │ undefined behavior†   │
48         │           │            │ behavior†      │                       │
49         ├───────────┼────────────┼────────────────┼───────────────────────┤
50         │DEFAULT    │ robust     │ undefined      │ error returned        │
51         │           │            │ behavior†      │                       │
52         └───────────┴────────────┴────────────────┴───────────────────────┘
53       †     If  the  mutex  type  is  PTHREAD_MUTEX_DEFAULT,  the behavior of
54             pthread_mutex_lock() may correspond to one  of  the  three  other
55             standard  mutex types as described in the table above. If it does
56             not correspond to one of those three, the behavior  is  undefined
57             for the cases marked †.
58
59       Where  the table indicates recursive behavior, the mutex shall maintain
60       the concept of a lock count. When  a  thread  successfully  acquires  a
61       mutex  for  the  first  time, the lock count shall be set to one. Every
62       time a thread relocks this mutex, the lock count shall  be  incremented
63       by one. Each time the thread unlocks the mutex, the lock count shall be
64       decremented by one. When the lock count reaches zero, the  mutex  shall
65       become available for other threads to acquire.
66
67       The   pthread_mutex_trylock()   function   shall   be   equivalent   to
68       pthread_mutex_lock(), except that if the  mutex  object  referenced  by
69       mutex  is  currently  locked  (by  any  thread,  including  the current
70       thread), the call shall  return  immediately.  If  the  mutex  type  is
71       PTHREAD_MUTEX_RECURSIVE and the mutex is currently owned by the calling
72       thread, the mutex lock count  shall  be  incremented  by  one  and  the
73       pthread_mutex_trylock() function shall immediately return success.
74
75       The pthread_mutex_unlock() function shall release the mutex object ref‐
76       erenced by mutex.  The manner in which a mutex is released is dependent
77       upon  the  mutex's  type attribute. If there are threads blocked on the
78       mutex object referenced by mutex when pthread_mutex_unlock() is called,
79       resulting  in the mutex becoming available, the scheduling policy shall
80       determine which thread shall acquire the mutex.
81
82       (In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex shall become
83       available  when the count reaches zero and the calling thread no longer
84       has any locks on this mutex.)
85
86       If a signal is delivered to a thread waiting for a mutex,  upon  return
87       from  the  signal handler the thread shall resume waiting for the mutex
88       as if it was not interrupted.
89
90       If mutex is a robust mutex and the process containing the owning thread
91       terminated while holding the mutex lock, a call to pthread_mutex_lock()
92       shall return the error value [EOWNERDEAD].  If mutex is a robust  mutex
93       and  the  owning thread terminated while holding the mutex lock, a call
94       to pthread_mutex_lock() may return the error value [EOWNERDEAD] even if
95       the  process  in which the owning thread resides has not terminated. In
96       these cases, the mutex is locked by the thread but the  state  it  pro‐
97       tects is marked as inconsistent. The application should ensure that the
98       state is made consistent for reuse  and  when  that  is  complete  call
99       pthread_mutex_consistent().   If  the  application is unable to recover
100       the state,  it  should  unlock  the  mutex  without  a  prior  call  to
101       pthread_mutex_consistent(), after which the mutex is marked permanently
102       unusable.
103
104       If mutex does not refer to an initialized mutex object, the behavior of
105       pthread_mutex_lock(),            pthread_mutex_trylock(),           and
106       pthread_mutex_unlock() is undefined.
107

RETURN VALUE

109       If successful, the pthread_mutex_lock(),  pthread_mutex_trylock(),  and
110       pthread_mutex_unlock() functions shall return zero; otherwise, an error
111       number shall be returned to indicate the error.
112

ERRORS

114       The pthread_mutex_lock() and  pthread_mutex_trylock()  functions  shall
115       fail if:
116
117       EAGAIN The  mutex  could  not be acquired because the maximum number of
118              recursive locks for mutex has been exceeded.
119
120       EINVAL The mutex was created with the  protocol  attribute  having  the
121              value  PTHREAD_PRIO_PROTECT and the calling thread's priority is
122              higher than the mutex's current priority ceiling.
123
124       ENOTRECOVERABLE
125              The state protected by the mutex is not recoverable.
126
127       EOWNERDEAD
128              The mutex is a robust mutex and the process containing the  pre‐
129              vious owning thread terminated while holding the mutex lock. The
130              mutex lock shall be acquired by the calling thread and it is  up
131              to the new owner to make the state consistent.
132
133       The pthread_mutex_lock() function shall fail if:
134
135       EDEADLK
136              The  mutex  type  is  PTHREAD_MUTEX_ERRORCHECK  and  the current
137              thread already owns the mutex.
138
139       The pthread_mutex_trylock() function shall fail if:
140
141       EBUSY  The mutex could not be acquired because it was already locked.
142
143       The pthread_mutex_unlock() function shall fail if:
144
145       EPERM  The    mutex     type     is     PTHREAD_MUTEX_ERRORCHECK     or
146              PTHREAD_MUTEX_RECURSIVE, or the mutex is a robust mutex, and the
147              current thread does not own the mutex.
148
149       The pthread_mutex_lock() and pthread_mutex_trylock() functions may fail
150       if:
151
152       EOWNERDEAD
153              The  mutex is a robust mutex and the previous owning thread ter‐
154              minated while holding the mutex lock. The mutex  lock  shall  be
155              acquired  by the calling thread and it is up to the new owner to
156              make the state consistent.
157
158       The pthread_mutex_lock() function may fail if:
159
160       EDEADLK
161              A deadlock condition was detected.
162
163       These functions shall not return an error code of [EINTR].
164
165       The following sections are informative.
166

EXAMPLES

168       None.
169

APPLICATION USAGE

171       Applications that have assumed that non-zero return values  are  errors
172       will  need  updating  for use with robust mutexes, since a valid return
173       for a thread acquiring a mutex which is protecting a  currently  incon‐
174       sistent  state  is  [EOWNERDEAD].   Applications  that do not check the
175       error returns, due to ruling out the possibility of such  errors  aris‐
176       ing,  should  not  use robust mutexes. If an application is supposed to
177       work with normal and robust mutexes it should check all  return  values
178       for error conditions and if necessary take appropriate action.
179

RATIONALE

181       Mutex objects are intended to serve as a low-level primitive from which
182       other thread synchronization functions  can  be  built.  As  such,  the
183       implementation  of mutexes should be as efficient as possible, and this
184       has ramifications on the features available at the interface.
185
186       The mutex functions and the particular default settings  of  the  mutex
187       attributes  have  been  motivated  by  the desire to not preclude fast,
188       inlined implementations of mutex locking and unlocking.
189
190       Since most attributes only need to be checked when a thread is going to
191       be  blocked,  the  use  of attributes does not slow the (common) mutex-
192       locking case.
193
194       Likewise, while being able to extract the thread ID of the owner  of  a
195       mutex  might  be desirable, it would require storing the current thread
196       ID when each mutex is locked, and this could incur unacceptable  levels
197       of overhead. Similar arguments apply to a mutex_tryunlock operation.
198
199       For  further  rationale  on the extended mutex types, see the Rationale
200       (Informative) volume of POSIX.1‐2017, Threads Extensions.
201
202       If an implementation detects that the  value  specified  by  the  mutex
203       argument  does  not  refer to an initialized mutex object, it is recom‐
204       mended that the function should fail and report an [EINVAL] error.
205

FUTURE DIRECTIONS

207       None.
208

SEE ALSO

210       pthread_mutex_consistent(), pthread_mutex_destroy(),
211       pthread_mutex_timedlock(), pthread_mutexattr_getrobust()
212
213       The  Base Definitions volume of POSIX.1‐2017, Section 4.12, Memory Syn‐
214       chronization, <pthread.h>
215
217       Portions of this text are reprinted and reproduced in  electronic  form
218       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
219       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
220       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
221       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
222       event of any discrepancy between this version and the original IEEE and
223       The Open Group Standard, the original IEEE and The Open Group  Standard
224       is  the  referee document. The original Standard can be obtained online
225       at http://www.opengroup.org/unix/online.html .
226
227       Any typographical or formatting errors that appear  in  this  page  are
228       most likely to have been introduced during the conversion of the source
229       files to man page format. To report such errors,  see  https://www.ker
230       nel.org/doc/man-pages/reporting_bugs.html .
231
232
233
234IEEE/The Open Group                  2017               PTHREAD_MUTEX_LOCK(3P)
Impressum