Provided by: manpages-fr-extra_20140201_all bug

NOM

       pthread_mutex_init,   pthread_mutex_lock,   pthread_mutex_trylock,   pthread_mutex_unlock,
       pthread_mutex_destroy - Opérations sur les mutex

SYNOPSIS

       #include <pthread.h>

       pthread_mutex_t fastmutex = PTHREAD_MUTEX_INITIALIZER;

       pthread_mutex_t recmutex = PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP;

       pthread_mutex_t errchkmutex = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;

       int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *mutexattr);

       int pthread_mutex_lock(pthread_mutex_t *mutex);

       int pthread_mutex_trylock(pthread_mutex_t *mutex);

       int pthread_mutex_unlock(pthread_mutex_t *mutex);

       int pthread_mutex_destroy(pthread_mutex_t *mutex);

DESCRIPTION

       Un mutex est un objet d'exclusion mutuelle (MUTual EXclusion), et  il  est  très  pratique
       pour  protéger  des données partagées de modifications simultanées et pour implémenter des
       sections critiques et moniteurs.

       Un mutex peut être dans deux états : déverrouillé (pris par aucun  thread)  ou  verrouillé
       (pris  par  un  thread).  Un  mutex ne peut être pris que par un seul thread à la fois. Un
       thread qui tente de verrouiller un mutex déjà verrouillé est suspendu jusqu'à  ce  que  le
       mutex soit déverrouillé.

       pthread_mutex_init()  initialise  le  mutex  pointé par mutex selon les attributs de mutex
       spécifié par mutexattr. Si mutexattr vaut NULL, les paramètres par défaut sont utilisés.

       L'implémentation LinuxThreads ne gère qu'un seul attribut, le type de mutex, qui peut être
       soit  « rapide »,  « récursif » ou à « vérification d'erreur ». Le type de mutex détermine
       s'il peut être verrouillé plusieurs fois par le  même  thread.  Le  type  par  défaut  est
       « rapide ».  Voyez pthread_mutexattr_init(3) pour plus d'informations sur les attributs de
       mutex.

       Les variables de type pthread_mutex_t peuvent aussi être initialisées de manière statique,
       en  utilisant  les  constantes  PTHREAD_MUTEX_INITIALIZER  (pour  les  mutex « rapides »),
       PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP    (pour    les     mutex     « récursifs »)     et
       PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP (pour les mutex à « vérification d'erreur »).

       pthread_mutex_lock()  verrouille  le  mutex.  Si  le  mutex  est  déverrouillé, il devient
       verrouillé et il est possédé par le thread appelant et pthread_mutex_lock() rend  la  main
       immédiatement.  Si  le  mutex  est déjà verrouillé par un autre thread, pthread_mutex_lock
       suspend le thread appelant jusqu'à ce que le mutex soit déverrouillé.

       Si  le  mutex  est  déjà  verrouillé  par  le  thread   appelant,   le   comportement   de
       pthread_mutex_lock()  dépend  du  type  du mutex. Si ce dernier est de type « rapide », le
       thread appelant est suspendu jusqu'à ce que le mutex soit déverrouillé, plaçant  ainsi  le
       thread  appelant en situation de blocage définitif. Si le mutex est de type « vérification
       d'erreur », pthread_mutex_lock() rend la main immédiatement avec le code d'erreur EDEADLK.
       Si le mutex est de type « récursif », pthread_mutex_lock() rend la main immédiatement avec
       un code de retour indiquant le succès,  enregistrant  le  nombre  de  fois  où  le  thread
       appelant a verrouillé le mutex. Un nombre égal d'appels à pthread_mutex_unlock() doit être
       réalisé avant que le mutex retourne à l'état déverrouillé.

       pthread_mutex_trylock() se comporte de la même manière que  pthread_mutex_lock(),  excepté
       qu'elle  ne  bloque  pas  le  thread appelant si le mutex est déjà verrouillé par un autre
       thread (ou par le thread appelant dans  le  cas  d'un  mutex  « rapide »).  Au  contraire,
       pthread_mutex_trylock() rend la main immédiatement avec le code d'erreur EBUSY.

       pthread_mutex_unlock()  déverrouille  le mutex. Celui-ci est supposé verrouillé, et ce par
       le thread courant en  entrant  dans  pthread_mutex_unlock().  Si  le  mutex  est  de  type
       « rapide »,  pthread_mutex_unlock()  le  réinitialise toujours à l'état déverrouillé. S'il
       est de type « récursif », son compteur de verrouillage est décrémenté (nombre d'opérations
       pthread_mutex_lock()  réalisées  sur  le  mutex  par  le thread appelant), et déverrouillé
       seulement quand ce compteur atteint 0.

       Sur les mutex « vérification d'erreur » et  « récursif »,  pthread_mutex_unlock()  vérifie
       lors de l'exécution que le mutex est verrouillé en entrant, et qu'il est verrouillé par le
       même thread que celui appelant  pthread_mutex_unlock()  Si  ces  conditions  ne  sont  pas
       réunies,  un code d'erreur est renvoyé et le mutex n'est pas modifié. Les mutex « rapide »
       ne réalisent pas de tels tests, permettant à un mutex verrouillé d'être  déverrouillé  par
       un  thread  autre que celui l'ayant verrouillé. Ce comportement n'est pas portable et l'on
       ne doit pas compter dessus.

       pthread_mutex_destroy() détruit un mutex, libérant les ressources qu'il détient. Le  mutex
       doit  être déverrouillé. Dans l'implémentation LinuxThreads, aucune ressource ne peut être
       associée à un mutex, aussi pthread_mutex_destroy() ne fait rien si ce n'est  vérifier  que
       le mutex n'est pas verrouillé.

ANNULATION

       Aucune   des  primitives  relatives  aux  mutex  n'est  un  point  d'annulation,  ni  même
       pthread_mutex_lock(), malgré le fait qu'il peut suspendre l'exécution du thread  pour  une
       longue  durée.  De cette manière, l'état des mutex aux points d'annulation est prévisible,
       permettant aux gestionnaires d'annulation  de  déverrouiller  précisément  ces  mutex  qui
       nécessitent   d'être   déverrouillés   avant   que   l'exécution  du  thread  ne  s'arrête
       définitivement.  Aussi,  les  threads  travaillant  en  mode  d'annulation   retardée   ne
       doivent-jamais verrouiller un mutex pour de longues périodes de temps.

ASYNC-SIGNAL SAFETY

       Les  fonctions relatives aux mutex ne sont pas fiables par rapport aux signaux asynchrones
       et ne doivent donc pas être utilisées dans des gestionnaires de signaux.  En  particulier,
       appeler pthread_mutex_lock() ou pthread_mutex_unlock() dans un gestionnaire de signal peut
       placer le thread appelant dans une situation de blocage définitif.

VALEUR RENVOYÉE

       pthread_mutex_init() retourne toujours 0. Les autres  fonctions  renvoient  0  en  cas  de
       succès et un code d'erreur non nul en cas de problème.

ERREURS

       La  fonction  pthread_mutex_lock()  renvoie  l'un  des  codes  d'erreur suivants en cas de
       problème :

              EINVAL Le mutex n'a pas été initialisé.

              EDEADLK
                     Le mutex est déjà verrouillé par le thread appelant (mutex à  « vérification
                     d'erreur » seulement).

       La  fonction  pthread_mutex_trylock()  renvoie  l'un des codes d'erreur suivants en cas de
       problème :

              EBUSY  Le mutex ne peut être verrouillé car il l'est déjà.

              EINVAL Le mutex n'a pas été initialisé.

       La fonction pthread_mutex_unlock() renvoie le code d'erreur suivant en cas de problème :

              EINVAL Le mutex n'a pas été initialisé.

              EPERM  Le  thread  appelant  ne  possède  pas  le  mutex  (mutex  à  « vérification
                     d'erreur » seulement).

       La fonction pthread_mutex_destroy() renvoie le code d'erreur suivant en cas de problème :

              EBUSY  Le mutex est déjà verrouillé.

AUTEUR

       Xavier Leroy <Xavier.Leroy@inria.fr>

VOIR AUSSI

       pthread_mutexattr_init(3), pthread_mutexattr_setkind_np(3), pthread_cancel(3).

EXEMPLE

       Une variable globale partagée x peut être protégée par un mutex comme suit :

              int x;
              pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;

       Tous  les  accès  et  modifications  de  x  doivent  être  entourés  de  paires d'appels à
       pthread_mutex_lock() et pthread_mutex_unlock() comme suit :

              pthread_mutex_lock(&mut);
              /* operate on x */
              pthread_mutex_unlock(&mut);

TRADUCTION

       Cette page de manuel a été traduite par Thierry Vignaud <tvignaud AT mandriva DOT com>  en
       2000  et  révisée  par  Alain  Portal  <aportal AT univ-montp2 DOT fr> en 2006. La version
       présente dans Debian est maintenue par les membres  de  la  liste  <debian-l10n-french  AT
       lists  DOT debian DOT org>. Veuillez signaler toute erreur de traduction par un rapport de
       bogue sur le paquet manpages-fr-extra.

                                           LinuxThreads                          PTHREAD_MUTEX(3)