NOM

       futex - Verrouillage rapide en mode utilisateur

SYNOPSIS

       #include <linux/futex.h>
       #include <sys/time.h>

       int futex(int *uaddr, int op, int val, const struct timespec *timeout,
                 int *uaddr2, int val3);

DESCRIPTION

       L'appel système futex() donne à un programme la possibilité d'attendre qu'une valeur à une adresse donnée
       change, ou de réveiller tous ceux qui sont en attente sur cette adresse. Bien  que  les  adresses  soient
       différentes  dans  des  processus  séparés,  le noyau fera la correspondance lors de l'appel système. Cet
       appel système est typiquement employé pour implémenter les verrous en mémoire partagée, tels qu'ils  sont
       décrits dans futex(7).

       Quand  une  opération  futex(7)  ne se termine pas de manière satisfaisante dans l'espace utilisateur, un
       appel au noyau est nécessaire pour l'arbitrage. Ceci signifie soit endormir le processus  appelant,  soit
       réveiller le processus en attente.

       Les  appelants de cette fonction doivent accepter les sémantiques décrites dans futex(7). Comme celles‐ci
       impliquent l'écriture d'instructions non portables en assembleur, leurs utilisateurs sont des auteurs  de
       bibliothèques plus que des développeurs applicatifs.

       Le  paramètre  uaddr doit pointer sur un entier aligné qui stocke le compteur. L'opération à exécuter est
       transmise dans le paramètre op, avec la valeur val.

       Cinq opérations sont définies pour le moment :

       FUTEX_WAIT
              Cette opération vérifie que l'adresse du futex uaddr contient toujours la valeur val  indiquée  et
              s'endort  en  attendant un FUTEX_WAKE à cette adresse. Les deux étapes sont liées atomiquement. Si
              l'argument timeout est non nul, il contient la durée  d’attente.  (Cet  intervalle  de  temps  est
              arrondi  à  la  granularité de l'horloge système et cet intervalle de blocage peut être légèrement
              modifié à cause des délais d'ordonnancement du  noyau.)  Si  timeout  est  nulle,  l’appel  bloque
              indéfiniment. Les arguments uaddr2 et val3 sont ignorés.

              D'après futex(7), cet appel est exécuté si la décrémentation du compteur donne une valeur négative
              (indiquant un conflit) et le sommeil durera jusqu'à ce qu'un autre processus relâche le  futex  et
              exécute FUTEX_WAKE.

       FUTEX_WAKE
              Cette  opération  réveille  au plus val processus en attente sur l'adresse du futex (endormis dans
              FUTEX_WAIT). Les arguments timeout, uaddr2 et val3 sont ignorés.

              D'après futex(7), ceci est exécuté si l'incrémentation du compteur montre qu'il y a des  processus
              en attente, une fois que la valeur du futex a été mise à 1 (indiquant qu'il est disponible).

       FUTEX_FD (présent jusqu'à Linux 2.6.25 inclus)
              Pour  permettre des réveils asynchrones, cette opération associe un descripteur de fichier avec un
              futex. Si un autre processus exécute un FUTEX_WAKE, l'appelant recevra le signal dont le numéro  a
              été  indiqué  dans  val. L'appelant doit refermer le descripteur de fichier après utilisation. Les
              arguments timeout, uaddr2 et val3 sont ignorés.

              Pour éviter les situations de concurrence, l'appelant doit tester si le futex a été  libéré  après
              le retour de FUTEX_FD.

              Parce qu'il était de façon inhérent sujet à des situations de concurrence, FUTEX_FD a été supprimé
              de Linux 2.6.26 et les suivants.

       FUTEX_REQUEUE (depuis Linux 2.5.70)
              Cette opération a été introduite dans le but d'éviter que trop de processus nécessitant  un  autre
              futex  ne soient activés lors de l'utilisation de FUTEX_WAKE. Cet appel réactive val processus, et
              remet en file d'attente tous les autres qui attendaient le futex à l'adresse uaddr2. Les arguments
              timeout et val3 sont ignorés.

       FUTEX_CMP_REQUEUE (depuis Linux 2.6.7)
              Il   y  a  un  problème  de  concurrence  dans  l'utilisation  prévue  pour  FUTEX_REQUEUE,  aussi
              FUTEX_CMP_REQUEUE a été introduit. Cette opération est similaire  à  FUTEX_REQUEUE,  sauf  qu'elle
              vérifie  si  l'adresse  uaddr  contient  encore  la  valeur  val3. Si non, l'opération échoue avec
              l'erreur EAGAIN.L'argument timeout est ignoré.

VALEUR RENVOYÉE

       En cas d'erreur, toutes les opérations renvoient -1, et errno contient le code  d'erreur.  La  valeur  de
       retour en cas de succès dépend de l'opération, conformément à la description de la liste suivante.

       FUTEX_WAIT
              Renvoie  O  si  le  processus  a  été réveillé par un appel FUTEX_WAKE. Consultez ERREURS pour les
              divers retours d'erreur possibles.

       FUTEX_WAKE
              Renvoie le nombre de processus réveillés.

       FUTEX_FD
              Renvoie le nouveau descripteur associé au futex.

       FUTEX_REQUEUE
              Renvoie le nombre de processus réveillés.

       FUTEX_CMP_REQUEUE
              Renvoie le nombre de processus réveillés.

ERREURS

       EACCES Pas d'accès en lecture à la mémoire futex.

       EAGAIN FUTEX_CMP_REQUEUE a détecté que la valeur pointée par uaddr n'est  pas  égale  à  la  valeur  val3
              attendue   (cela   indique   probablement  une  situation  de  compétition ;  utilisez  maintenant
              FUTEX_WAKE).

       EFAULT Erreur de récupération du renseignement timeout depuis l'espace utilisateur.

       EINTR  Une opération FUTEX_WAIT a été interrompue par  un  signal  (consultez  signal(7))  ou  un  réveil
              involontaire.

       EINVAL Argument incorrect.

       ENFILE La limite du nombre total de fichiers ouverts sur le système a été atteinte.

       ENOSYS op contient une opération non valable.

       ETIMEDOUT
              Temps d'attente atteint pendant l'opération FUTEX_WAIT.

       EWOULDBLOCK
              op  était  FUTEX_WAIT et la valeur pointée par uaddr n'était pas égale à la valeur val attendue au
              moment de l'appel.

VERSIONS

       Le support initial des futex a été ajouté dans Linux 2.5.7 mais avec une sémantique différente  de  celle
       décrite  ci‐dessus.  Un  appel  système  à  4 paramètres avec la sémantique décrite dans cette page a été
       ajouté dans Linux 2.5.40. Dans Linux 2.5.70,  un  paramètre  supplémentaire  a  été  ajouté.  Un  sixième
       paramètre a été ajouté dans Linux 2.6.7 — compliqué, surtout sur l'architecture s390.

CONFORMITÉ

       Cet appel système est spécifique à Linux.

NOTES

       Répétons‐le,  les  futex  de  base  ne  sont  pas conçus comme une abstraction facile à employer pour les
       utilisateurs (mais la glibc ne fournit pas de fonction autour de cet appel  système).  Les  implémenteurs
       doivent  maîtriser  l'assembleur et avoir lu les sources de la bibliothèque en espace utilisateur décrite
       ci-dessous.

VOIR AUSSI

       restart_syscall(2), futex(7)

       « Fuss, Futexes and Furwocks: Fast  Userlevel  Locking  in  Linux »  (proceedings  of  the  Ottawa  Linux
       Symposium 2002), disponible en ligne à
       ⟨http://kernel.org/doc/ols/2002/ols2002-pages-479-495.pdf⟩

       La bibliothèque d'exemple de futex, futex-*.tar.bz2 à
       ⟨ftp://ftp.kernel.org/pub/linux/kernel/people/rusty/⟩

COLOPHON

       Cette page fait partie de la publication 3.65 du projet man-pages Linux. Une description du projet et des
       instructions    pour    signaler    des    anomalies    peuvent     être     trouvées     à     l'adresse
       http://www.kernel.org/doc/man-pages/.

TRADUCTION

       Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a <http://po4a.alioth.debian.org/> par
       l'équipe de traduction francophone au sein du projet perkamon <http://perkamon.alioth.debian.org/>.

       Christophe      Blaess      <http://www.blaess.fr/christophe/>      (1996-2003),       Alain       Portal
       <http://manpagesfr.free.fr/>  (2003-2006).  Julien  Cristau  et  l'équipe  francophone  de  traduction de
       Debian (2006-2009).

       Veuillez signaler toute erreur de traduction en écrivant à <debian-l10n-french@lists.debian.org>  ou  par
       un rapport de bogue sur le paquet manpages-fr.

       Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la commande « man -L C
       <section> <page_de_man> ».