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
11

NAME

13       pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock —  lock
14       and unlock a mutex
15

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

EXAMPLES

169       None.
170

APPLICATION USAGE

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

RATIONALE

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

FUTURE DIRECTIONS

208       None.
209

SEE ALSO

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