<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <HTML> <HEAD> <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8"> <TITLE>PTHREAD_MUTEX(3) manual page</TITLE> <META NAME="GENERATOR" CONTENT="OpenOffice.org 1.1.3 (Linux)"> <META NAME="CREATED" CONTENT="20050505;5000"> <META NAME="CHANGED" CONTENT="20050505;19000600"> <!-- manual page source format generated by PolyglotMan v3.2, --> <!-- available at http://polyglotman.sourceforge.net/ --> </HEAD> <BODY LANG="en-GB" BGCOLOR="#ffffff" DIR="LTR"> <H4>POSIX Threads for Windows – REFERENCE - <A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A></H4> <P><A HREF="index.html">Reference Index</A></P> <P><A HREF="#toc">Table of Contents</A></P> <H2><A HREF="#toc0" NAME="sect0">Name</A></H2> <P>pthread_mutex_init, pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_timedlock, pthread_mutex_unlock, pthread_mutex_destroy - operations on mutexes </P> <H2><A HREF="#toc1" NAME="sect1">Synopsis</A></H2> <P><B>#include <pthread.h></B> </P> <P><B>#include <time.h></B></P> <P><B>pthread_mutex_t </B><I>fastmutex</I> <B>= PTHREAD_MUTEX_INITIALIZER;</B> </P> <P><B>pthread_mutex_t </B><I>recmutex</I> <B>= PTHREAD_RECURSIVE_MUTEX_INITIALIZER;</B> </P> <P><B>pthread_mutex_t </B><I>errchkmutex</I> <B>= PTHREAD_ERRORCHECK_MUTEX_INITIALIZER;</B> </P> <P><B>pthread_mutex_t </B><I>recmutex</I> <B>= PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP;</B> </P> <P><B>pthread_mutex_t </B><I>errchkmutex</I> <B>= PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;</B> </P> <P><B>int pthread_mutex_init(pthread_mutex_t *</B><I>mutex</I><B>, const pthread_mutexattr_t *</B><I>mutexattr</I><B>);</B> </P> <P><B>int pthread_mutex_lock(pthread_mutex_t *</B><I>mutex</I><B>);</B> </P> <P><B>int pthread_mutex_trylock(pthread_mutex_t *</B><I>mutex</I><B>);</B> </P> <P><B>int pthread_mutex_timedlock(pthread_mutex_t *</B><I>mutex, </I><B>const struct timespec *</B><I>abs_timeout</I><B>);</B> </P> <P><B>int pthread_mutex_unlock(pthread_mutex_t *</B><I>mutex</I><B>);</B> </P> <P><B>int pthread_mutex_destroy(pthread_mutex_t *</B><I>mutex</I><B>);</B> </P> <H2><A HREF="#toc2" NAME="sect2">Description</A></H2> <P>A mutex is a MUTual EXclusion device, and is useful for protecting shared data structures from concurrent modifications, and implementing critical sections and monitors. </P> <P>A mutex has two possible states: unlocked (not owned by any thread), and locked (owned by one thread). A mutex can never be owned by two different threads simultaneously. A thread attempting to lock a mutex that is already locked by another thread is suspended until the owning thread unlocks the mutex first. </P> <P><B>pthread_mutex_init</B> initializes the mutex object pointed to by <I>mutex</I> according to the mutex attributes specified in <I>mutexattr</I>. If <I>mutexattr</I> is <B>NULL</B>, default attributes are used instead. </P> <P>The type of a mutex determines whether it can be locked again by a thread that already owns it. The default type is “normal”. See <A HREF="pthread_mutexattr_init.html"><B>pthread_mutexattr_init</B>(3)</A> for more information on mutex attributes. </P> <P>Variables of type <B>pthread_mutex_t</B> can also be initialized statically, using the constants <B>PTHREAD_MUTEX_INITIALIZER</B> (for normal “fast” mutexes), <B>PTHREAD_RECURSIVE_MUTEX_INITIALIZER</B> (for recursive mutexes), and <B>PTHREAD_ERRORCHECK_MUTEX_INITIALIZER</B> (for error checking mutexes). <SPAN STYLE="font-weight: medium"> In the <B>Pthreads-w32</B> implementation, an application should still call <B>pthread_mutex_destroy</B> at some point to ensure that any resources consumed by the mutex are released.</SPAN></P> <P><B>pthread_mutex_lock</B> locks the given mutex. If the mutex is currently unlocked, it becomes locked and owned by the calling thread, and <B>pthread_mutex_lock</B> returns immediately. If the mutex is already locked by another thread, <B>pthread_mutex_lock</B> suspends the calling thread until the mutex is unlocked. </P> <P>If the mutex is already locked by the calling thread, the behavior of <B>pthread_mutex_lock</B> depends on the type of the mutex. If the mutex is of the “normal” type, the calling thread is suspended until the mutex is unlocked, thus effectively causing the calling thread to deadlock. If the mutex is of the ‘‘error checking’’ type, <B>pthread_mutex_lock</B> returns immediately with the error code <B>EDEADLK</B>. If the mutex is of the ‘‘recursive’’ type, <B>pthread_mutex_lock</B> succeeds and returns immediately, recording the number of times the calling thread has locked the mutex. An equal number of <B>pthread_mutex_unlock</B> operations must be performed before the mutex returns to the unlocked state. </P> <P><B>pthread_mutex_trylock</B> behaves identically to <B>pthread_mutex_lock</B>, except that it does not block the calling thread if the mutex is already locked by another thread (or by the calling thread in the case of a “normal” mutex). Instead, <B>pthread_mutex_trylock</B> returns immediately with the error code <B>EBUSY</B>. </P> <P><B>pthread_mutex_timedlock</B> behaves identically to <B>pthread_mutex_lock</B>, except that if it cannot acquire the lock before the <I>abs_timeout</I> time, the call returns with the error code <B>ETIMEDOUT</B>. If the mutex can be locked immediately it is, and the <B>abs_timeout</B> parameter is ignored.</P> <P><B>pthread_mutex_unlock</B> unlocks the given mutex. The mutex is assumed to be locked and owned by the calling thread on entrance to <B>pthread_mutex_unlock</B>. If the mutex is of the “normal” type, <B>pthread_mutex_unlock</B> always returns it to the unlocked state. If it is of the ‘‘recursive’’ type, it decrements the locking count of the mutex (number of <B>pthread_mutex_lock</B> operations performed on it by the calling thread), and only when this count reaches zero is the mutex actually unlocked. </P> <P>On ‘‘error checking’’ mutexes, <B>pthread_mutex_unlock</B> actually checks at run-time that the mutex is locked on entrance, and that it was locked by the same thread that is now calling <B>pthread_mutex_unlock</B>. If these conditions are not met, an error code is returned and the mutex remains unchanged. ‘‘Normal’’ mutexes perform no such checks, thus allowing a locked mutex to be unlocked by a thread other than its owner. This is non-portable behavior and is not meant to be used as a feature.</P> <P><B>pthread_mutex_destroy</B> destroys a mutex object, freeing the resources it might hold. The mutex must be unlocked on entrance.</P> <H2><A HREF="#toc3" NAME="sect3">Cancellation</A></H2> <P>None of the mutex functions is a cancellation point, not even <B>pthread_mutex_lock</B>, in spite of the fact that it can suspend a thread for arbitrary durations. This way, the status of mutexes at cancellation points is predictable, allowing cancellation handlers to unlock precisely those mutexes that need to be unlocked before the thread stops executing. Consequently, threads using deferred cancellation should never hold a mutex for extended periods of time. </P> <H2><A HREF="#toc4" NAME="sect4">Async-signal Safety</A></H2> <P>The mutex functions are not async-signal safe. What this means is that they should not be called from a signal handler. In particular, calling <B>pthread_mutex_lock</B> or <B>pthread_mutex_unlock</B> from a signal handler may deadlock the calling thread. </P> <H2><A HREF="#toc5" NAME="sect5">Return Value</A></H2> <P><B>pthread_mutex_init</B> always returns 0. The other mutex functions return 0 on success and a non-zero error code on error. </P> <H2><A HREF="#toc6" NAME="sect6">Errors</A></H2> <P>The <B>pthread_mutex_lock</B> function returns the following error code on error: </P> <DL> <DL> <DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B> </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm"> the mutex has not been properly initialized. </DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"> <B>EDEADLK</B> </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm"> the mutex is already locked by the calling thread (‘‘error checking’’ mutexes only). </DD></DL> </DL> <P> The <B>pthread_mutex_trylock</B> function returns the following error codes on error: </P> <DL> <DL> <DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EBUSY</B> </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm"> the mutex could not be acquired because it was currently locked. </DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"> <B>EINVAL</B> </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm"> the mutex has not been properly initialized. </DD></DL> </DL> <P> The <B>pthread_mutex_timedlock</B> function returns the following error codes on error: </P> <DL> <DL> <DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>ETIMEDOUT</B> </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm"> the mutex could not be acquired before the <I>abs_timeout</I> time arrived. </DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"> <B>EINVAL</B> </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm"> the mutex has not been properly initialized. </DD></DL> </DL> <P> The <B>pthread_mutex_unlock</B> function returns the following error code on error: </P> <DL> <DL> <DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B> </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm"> the mutex has not been properly initialized. </DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"> <B>EPERM</B> </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm"> the calling thread does not own the mutex (‘‘error checking’’ mutexes only). </DD></DL> </DL> <P> The <B>pthread_mutex_destroy</B> function returns the following error code on error: </P> <DL> <DL> <DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EBUSY</B> </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm"> the mutex is currently locked. </DD></DL> </DL> <H2> <A HREF="#toc7" NAME="sect7">Author</A></H2> <P>Xavier Leroy <Xavier.Leroy@inria.fr> </P> <P>Modified by Ross Johnson for use with <A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A>.</P> <H2><A HREF="#toc8" NAME="sect8">See Also</A></H2> <P><A HREF="pthread_mutexattr_init.html"><B>pthread_mutexattr_init</B>(3)</A> , <A HREF="pthread_mutexattr_init.html"><B>pthread_mutexattr_settype</B>(3)</A> , <A HREF="pthread_cancel.html"><B>pthread_cancel</B>(3)</A> . </P> <H2><A HREF="#toc9" NAME="sect9">Example</A></H2> <P>A shared global variable <I>x</I> can be protected by a mutex as follows: </P> <PRE STYLE="margin-left: 1cm; margin-right: 1cm">int x; pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;</PRE><BLOCKQUOTE STYLE="margin-left: 0cm; margin-right: 0cm"> All accesses and modifications to <I>x</I> should be bracketed by calls to <B>pthread_mutex_lock</B> and <B>pthread_mutex_unlock</B> as follows: </BLOCKQUOTE> <PRE STYLE="margin-left: 1.03cm; margin-right: 2cm">pthread_mutex_lock(&mut); /* operate on x */ pthread_mutex_unlock(&mut);</PRE> <HR> <BLOCKQUOTE STYLE="margin-right: 4cm"><A NAME="toc"></A><B>Table of Contents</B></BLOCKQUOTE> <UL> <LI><BLOCKQUOTE STYLE="margin-right: 4cm; margin-bottom: 0cm"><A HREF="#sect0" NAME="toc0">Name</A> </BLOCKQUOTE> <LI><BLOCKQUOTE STYLE="margin-right: 4cm; margin-bottom: 0cm"><A HREF="#sect1" NAME="toc1">Synopsis</A> </BLOCKQUOTE> <LI><BLOCKQUOTE STYLE="margin-right: 4cm; margin-bottom: 0cm"><A HREF="#sect2" NAME="toc2">Description</A> </BLOCKQUOTE> <LI><BLOCKQUOTE STYLE="margin-right: 4cm; margin-bottom: 0cm"><A HREF="#sect3" NAME="toc3">Cancellation</A> </BLOCKQUOTE> <LI><BLOCKQUOTE STYLE="margin-right: 4cm; margin-bottom: 0cm"><A HREF="#sect4" NAME="toc4">Async-signal Safety</A> </BLOCKQUOTE> <LI><BLOCKQUOTE STYLE="margin-right: 4cm; margin-bottom: 0cm"><A HREF="#sect5" NAME="toc5">Return Value</A> </BLOCKQUOTE> <LI><BLOCKQUOTE STYLE="margin-right: 4cm; margin-bottom: 0cm"><A HREF="#sect6" NAME="toc6">Errors</A> </BLOCKQUOTE> <LI><BLOCKQUOTE STYLE="margin-right: 4cm; margin-bottom: 0cm"><A HREF="#sect7" NAME="toc7">Author</A> </BLOCKQUOTE> <LI><BLOCKQUOTE STYLE="margin-right: 4cm; margin-bottom: 0cm"><A HREF="#sect8" NAME="toc8">See Also</A> </BLOCKQUOTE> <LI><BLOCKQUOTE STYLE="margin-right: 4cm"><A HREF="#sect9" NAME="toc9">Example</A> </BLOCKQUOTE> </UL> </BODY> </HTML>