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.57 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> ».