1pthread_mutex_lock(3C)   Standard C Library Functions   pthread_mutex_lock(3C)
2
3
4

NAME

6       pthread_mutex_lock,  pthread_mutex_trylock, pthread_mutex_unlock - lock
7       or unlock a mutex
8

SYNOPSIS

10       cc -mt [ flag... ] file... -lpthread [ library... ]
11       #include <pthread.h>
12
13       int pthread_mutex_lock(pthread_mutex_t *mutex);
14
15
16       int pthread_mutex_trylock(pthread_mutex_t *mutex);
17
18
19       int pthread_mutex_unlock(pthread_mutex_t *mutex);
20
21

DESCRIPTION

23       The  mutex  object  referenced  by   mutex   is   locked   by   calling
24       pthread_mutex_lock().  If  the  mutex  is  already  locked, the calling
25       thread blocks until the mutex becomes available. This operation returns
26       with  the mutex object referenced by mutex in the locked state with the
27       calling thread as its owner.
28
29
30       If the mutex type is  PTHREAD_MUTEX_NORMAL, deadlock detection  is  not
31       provided.  Attempting  to relock the mutex causes deadlock. If a thread
32       attempts to unlock a mutex that it has not locked or a  mutex  that  is
33       unlocked, undefined behavior results.
34
35
36       If  the mutex type is  PTHREAD_MUTEX_ERRORCHECK, then error checking is
37       provided. If a thread attempts to relock a mutex that  it  has  already
38       locked,  an  error  will  be returned. If a thread attempts to unlock a
39       mutex that it has not locked or a mutex which  is  unlocked,  an  error
40       will be returned.
41
42
43       If  the  mutex  type is  PTHREAD_MUTEX_RECURSIVE, then the mutex  main‐
44       tains the concept of a lock count. When a thread successfully  acquires
45       a  mutex  for  the first time, the lock count is set to 1. Every time a
46       thread relocks this mutex, the lock count is  incremented by one.  Each
47       time  the  thread  unlocks  the mutex, the lock count is decremented by
48       one. When the lock count reaches  0, the mutex  becomes  available  for
49       other  threads to acquire. If a thread  attempts to unlock a mutex that
50       it has not locked or a  mutex  that  is  unlocked,  an  error  will  be
51       returned.
52
53
54       If  the mutex type is  PTHREAD_MUTEX_DEFAULT, attempting to recursively
55       lock the mutex results in undefined behavior. Attempting to  unlock the
56       mutex  if  it was not locked by the calling thread results in undefined
57       behavior. Attempting to unlock the mutex if it is not locked results in
58       undefined behavior.
59
60
61       The     pthread_mutex_trylock()     function     is     identical    to
62       pthread_mutex_lock() except that if  the  mutex  object  referenced  by
63       mutex  is  currently  locked  (by  any  thread,  including  the current
64       thread), the call fails immediately with EBUSY.
65
66
67       The pthread_mutex_unlock() function releases the  mutex  object  refer‐
68       enced  by  mutex.  The manner in which a mutex is released is dependent
69       upon the mutex's type attribute. If there are threads  blocked  on  the
70       mutex object referenced by mutex when pthread_mutex_unlock() is called,
71       resulting in the mutex  becoming available, the  scheduling  policy  is
72       used to determine  which thread will acquire the mutex. (In the case of
73       PTHREAD_MUTEX_RECURSIVE mutexes, the mutex becomes available  when  the
74       count reaches  0 and the calling thread no longer has any locks on this
75       mutex.)
76
77
78       If a signal is delivered to a thread waiting for a mutex,  upon  return
79       from  the signal handler the thread resumes waiting for the mutex as if
80       it was not interrupted.
81

RETURN VALUES

83       If successful, the   pthread_mutex_lock()  and   pthread_mutex_unlock()
84       functions return  0. Otherwise, an error number is returned to indicate
85       the error.
86
87
88       The  pthread_mutex_trylock() function returns  0 if a lock on the mutex
89       object  referenced  by mutex is acquired. Otherwise, an error number is
90       returned to indicate the error.
91

ERRORS

93       The  pthread_mutex_lock() and  pthread_mutex_trylock()  functions  will
94       fail if:
95
96       EAGAIN    The mutex could not be acquired because the maximum number of
97                 recursive locks for mutex has been exceeded.
98
99
100       EINVAL    The mutex was created with the protocol attribute having  the
101                 value  PTHREAD_PRIO_PROTECT and the calling thread's priority
102                 is higher than the mutex's current priority ceiling.
103
104
105       EPERM     The mutex was created with the protocol attribute having  the
106                 value  PTHREAD_PRIO_PROTECT  and the calling thread is not in
107                 the  real-time  class  (SCHED_RR  or  SCHED_FIFO   scheduling
108                 class).
109
110
111
112       The  pthread_mutex_trylock() function will fail if:
113
114       EBUSY    The mutex could not be acquired because it was already locked.
115
116
117
118       The        pthread_mutex_lock(),       pthread_mutex_trylock()      and
119       pthread_mutex_unlock() functions may fail if:
120
121       EINVAL    The value specified by mutex does not refer to an initialized
122                 mutex object.
123
124
125
126       The  pthread_mutex_lock() function may fail if:
127
128       EDEADLK    The current thread already owns the mutex.
129
130
131       ENOMEM     The  limit  on the number of simultaneously held mutexes has
132                  been exceeded.
133
134
135
136       The  pthread_mutex_unlock() function will fail if:
137
138       EPERM    The mutex type is PTHREAD_MUTEX_ERRORCHECK or the mutex  is  a
139                robust mutex, and the current thread does not own the mutex.
140
141
142
143       When    a    thread   makes   a   call   to   pthread_mutex_lock()   or
144       pthread_mutex_trylock(), if the mutex is initialized with  the  robust‐
145       ness    attribute    having   the   value   PTHREAD_MUTEX_ROBUST   (see
146       pthread_mutexattr_getrobust(3C)), the call will return these error val‐
147       ues if:
148
149       EOWNERDEAD         The  last owner of this mutex died while holding the
150                          mutex, or the process containing the  owner  of  the
151                          mutex  unmapped  the  memory containing the mutex or
152                          performed one of the exec(2) functions.  This  mutex
153                          is  now  owned  by  the  caller. The caller must now
154                          attempt to make the state  protected  by  the  mutex
155                          consistent.  If  it  is  able to clean up the state,
156                          then it should call  pthread_mutex_consistent()  for
157                          the  mutex and unlock the mutex. Subsequent calls to
158                          pthread_mutex_lock()   and   pthread_mutex_trylock()
159                          will  behave  normally,  as before. If the caller is
160                          not able to clean up the  state,  pthread_mutex_con‐
161                          sistent()  should  not  be called for the mutex, but
162                          the mutex should be unlocked.  Subsequent  calls  to
163                          pthread_mutex_lock()   and   pthread_mutex_trylock()
164                          will fail to acquire the mutex with the error  value
165                          ENOTRECOVERABLE.  If the owner who acquired the lock
166                          with EOWNERDEAD dies, the next  owner  will  acquire
167                          the lock with EOWNERDEAD.
168
169
170       ENOTRECOVERABLE    The  mutex  trying to be acquired was protecting the
171                          state  that  has  been  left  irrecoverable  by  the
172                          mutex's last owner. The mutex has not been acquired.
173                          This condition can occur when the  lock  was  previ‐
174                          ously  acquired  with  EOWNERDEAD, and the owner was
175                          not able to clean up  the  state  and  unlocked  the
176                          mutex without calling pthread_mutex_consistent().
177
178

ATTRIBUTES

180       See attributes(5) for descriptions of the following attributes:
181
182
183
184
185       ┌─────────────────────────────┬─────────────────────────────┐
186       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
187       ├─────────────────────────────┼─────────────────────────────┤
188       │Interface Stability          │Committed                    │
189       ├─────────────────────────────┼─────────────────────────────┤
190       │MT-Level                     │MT-Safe                      │
191       ├─────────────────────────────┼─────────────────────────────┤
192       │Standard                     │See standards(5).            │
193       └─────────────────────────────┴─────────────────────────────┘
194

SEE ALSO

196       pthread_mutex_consistent(3C),   pthread_mutex_init(3C),  pthread_mutex‐
197       attr_setprotocol(3C),  pthread_mutexattr_setrobust(3C),  pthread_mutex‐
198       attr_settype(3C), attributes(5), standards(5)
199

NOTES

201       In   the   current  implementation  of  threads,  pthread_mutex_lock(),
202       pthread_mutex_unlock(),          mutex_lock(),          mutex_unlock(),
203       pthread_mutex_trylock(),  and mutex_trylock() do not validate the mutex
204       type.  Therefore, an uninitialized mutex or a  mutex  with  an  invalid
205       type  does  not  return  EINVAL. Interfaces for mutexes with an invalid
206       type have unspecified behavior.
207
208
209       Uninitialized mutexes that are allocated locally may contain junk data.
210       Such  mutexes  need  to  be  initialized using  pthread_mutex_init() or
211       mutex_init().
212
213
214
215SunOS 5.11                        11 Nov 2008           pthread_mutex_lock(3C)
Impressum