debian/local/manpages/pthread_mutex_init.3

   1 .TH PTHREAD_MUTEX 3 LinuxThreads
   2
   3
   4 .SH NAME
   5 pthread_mutex_init, pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock, pthread_mutex_destroy \- operations on mutexes
   6
   7 .SH SYNOPSIS
   8 .B #include <pthread.h>
   9
  10 .BI "pthread_mutex_t " fastmutex " = PTHREAD_MUTEX_INITIALIZER;"
  11
  12 .BI "pthread_mutex_t " recmutex " = PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP;"
  13
  14 .BI "pthread_mutex_t " errchkmutex " = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;"
  15
  16 .BI "int pthread_mutex_init(pthread_mutex_t *" mutex ", const pthread_mutexattr_t *" mutexattr ");"
  17
  18 .BI "int pthread_mutex_lock(pthread_mutex_t *" mutex ");"
  19
  20 .BI "int pthread_mutex_trylock(pthread_mutex_t *" mutex ");"
  21
  22 .BI "int pthread_mutex_unlock(pthread_mutex_t *" mutex ");"
  23
  24 .BI "int pthread_mutex_destroy(pthread_mutex_t *" mutex ");"
  25
  26 .SH DESCRIPTION
  27 A mutex is a MUTual EXclusion device, and is useful for protecting
  28 shared data structures from concurrent modifications, and implementing
  29 critical sections and monitors.
  30
  31 A mutex has two possible states: unlocked (not owned by any thread),
  32 and locked (owned by one thread). A mutex can never be owned by two
  33 different threads simultaneously. A thread attempting to lock a mutex
  34 that is already locked by another thread is suspended until the owning
  35 thread unlocks the mutex first.
  36
  37 \fBpthread_mutex_init\fP initializes the mutex object pointed to by
  38 \fImutex\fP according to the mutex attributes specified in \fImutexattr\fP.
  39 If \fImutexattr\fP is \fBNULL\fP, default attributes are used instead.
  40
  41 The LinuxThreads implementation supports only one mutex attributes,
  42 the \fImutex kind\fP, which is either ``fast'', ``recursive'', or
  43 ``error checking''. The kind of a mutex determines whether
  44 it can be locked again by a thread that already owns it.
  45 The default kind is ``fast''. See \fBpthread_mutexattr_init\fP(3) for more
  46 information on mutex attributes.
  47
  48 Variables of type \fBpthread_mutex_t\fP can also be initialized
  49 statically, using the constants \fBPTHREAD_MUTEX_INITIALIZER\fP (for fast
  50 mutexes), \fBPTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP\fP (for recursive
  51 mutexes), and \fBPTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP\fP (for error checking
  52 mutexes).
  53
  54 \fBpthread_mutex_lock\fP locks the given mutex. If the mutex is currently
  55 unlocked, it becomes locked and owned by the calling thread, and
  56 \fBpthread_mutex_lock\fP returns immediately. If the mutex is already
  57 locked by another thread, \fBpthread_mutex_lock\fP suspends the calling
  58 thread until the mutex is unlocked.
  59
  60 If the mutex is already locked by the calling thread, the behavior of
  61 \fBpthread_mutex_lock\fP depends on the kind of the mutex. If the mutex is
  62 of the ``fast'' kind, the calling thread is suspended until the mutex
  63 is unlocked, thus effectively causing the calling thread to
  64 deadlock. If the mutex is of the ``error checking'' kind,
  65 \fBpthread_mutex_lock\fP returns immediately with the error code \fBEDEADLK\fP.
  66 If the mutex is of the ``recursive'' kind, \fBpthread_mutex_lock\fP
  67 succeeds and returns immediately, recording the number of times the
  68 calling thread has locked the mutex. An equal number of
  69 \fBpthread_mutex_unlock\fP operations must be performed before the mutex
  70 returns to the unlocked state.
  71
  72 \fBpthread_mutex_trylock\fP behaves identically to \fBpthread_mutex_lock\fP,
  73 except that it does not block the calling thread if the mutex is
  74 already locked by another thread (or by the calling thread in the case
  75 of a ``fast'' mutex). Instead, \fBpthread_mutex_trylock\fP returns
  76 immediately with the error code \fBEBUSY\fP.
  77
  78 \fBpthread_mutex_unlock\fP unlocks the given mutex. The mutex is assumed
  79 to be locked and owned by the calling thread on entrance to
  80 \fBpthread_mutex_unlock\fP. If the mutex is of the ``fast'' kind,
  81 \fBpthread_mutex_unlock\fP always returns it to the unlocked state. If it
  82 is of the ``recursive'' kind, it decrements the locking count of the
  83 mutex (number of \fBpthread_mutex_lock\fP operations performed on it by
  84 the calling thread), and only when this count reaches zero is the
  85 mutex actually unlocked.
  86
  87 On ``error checking'' and ``recursive'' mutexes,
  88 \fBpthread_mutex_unlock\fP actually checks at run-time that the mutex is
  89 locked on entrance, and that it was locked by the same thread that is
  90 now calling \fBpthread_mutex_unlock\fP.  If these conditions are not met,
  91 an error code is returned and the mutex remains unchanged.  ``Fast''
  92 mutexes perform no such checks, thus allowing a locked mutex to be
  93 unlocked by a thread other than its owner. This is non-portable behavior
  94 and must not be relied upon.
  95
  96 \fBpthread_mutex_destroy\fP destroys a mutex object, freeing the resources
  97 it might hold. The mutex must be unlocked on entrance. In the
  98 LinuxThreads implementation, no resources are associated with mutex
  99 objects, thus \fBpthread_mutex_destroy\fP actually does nothing except
 100 checking that the mutex is unlocked.
 101
 102 .SH CANCELLATION
 103
 104 None of the mutex functions is a cancellation point, not even
 105 \fBpthread_mutex_lock\fP, in spite of the fact that it can suspend a
 106 thread for arbitrary durations. This way, the status of mutexes at
 107 cancellation points is predictable, allowing cancellation handlers to
 108 unlock precisely those mutexes that need to be unlocked before the
 109 thread stops executing. Consequently, threads using deferred
 110 cancellation should never hold a mutex for extended periods of time.
 111
 112 .SH "ASYNC-SIGNAL SAFETY"
 113
 114 The mutex functions are not async-signal safe. What this means is that
 115 they should not be called from a signal handler. In particular,
 116 calling \fBpthread_mutex_lock\fP or \fBpthread_mutex_unlock\fP from a signal
 117 handler may deadlock the calling thread.
 118
 119 .SH "RETURN VALUE"
 120
 121 \fBpthread_mutex_init\fP always returns 0. The other mutex functions
 122 return 0 on success and a non-zero error code on error.
 123
 124 .SH ERRORS
 125
 126 The \fBpthread_mutex_lock\fP function returns the following error code
 127 on error:
 128 .RS
 129 .TP
 130 \fBEINVAL\fP
 131 the mutex has not been properly initialized.
 132
 133 .TP
 134 \fBEDEADLK\fP
 135 the mutex is already locked by the calling thread
 136 (``error checking'' mutexes only).
 137 .RE
 138
 139 The \fBpthread_mutex_trylock\fP function returns the following error codes
 140 on error:
 141 .RS
 142 .TP
 143 \fBEBUSY\fP
 144 the mutex could not be acquired because it was currently locked.
 145
 146 .TP
 147 \fBEINVAL\fP
 148 the mutex has not been properly initialized.
 149 .RE
 150
 151 The \fBpthread_mutex_unlock\fP function returns the following error code
 152 on error:
 153 .RS
 154 .TP
 155 \fBEINVAL\fP
 156 the mutex has not been properly initialized.
 157
 158 .TP
 159 \fBEPERM\fP
 160 the calling thread does not own the mutex (``error checking'' mutexes only).
 161 .RE
 162
 163 The \fBpthread_mutex_destroy\fP function returns the following error code
 164 on error:
 165 .RS
 166 .TP
 167 \fBEBUSY\fP
 168 the mutex is currently locked.
 169 .RE
 170
 171 .SH AUTHOR
 172 Xavier Leroy <Xavier.Leroy@inria.fr>
 173
 174 .SH "SEE ALSO"
 175 \fBpthread_mutexattr_init\fP(3),
 176 \fBpthread_mutexattr_setkind_np\fP(3),
 177 \fBpthread_cancel\fP(3).
 178
 179 .SH EXAMPLE
 180
 181 A shared global variable \fIx\fP can be protected by a mutex as follows:
 182
 183 .RS
 184 .ft 3
 185 .nf
 186 .sp
 187 int x;
 188 pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
 189 .ft
 190 .LP
 191 .RE
 192 .fi
 193
 194 All accesses and modifications to \fIx\fP should be bracketed by calls to
 195 \fBpthread_mutex_lock\fP and \fBpthread_mutex_unlock\fP as follows:
 196
 197 .RS
 198 .ft 3
 199 .nf
 200 .sp
 201 pthread_mutex_lock(&mut);
 202 /* operate on x */
 203 pthread_mutex_unlock(&mut);
 204 .ft
 205 .LP
 206 .RE
 207 .fi
 208
 209