int eventfd(unsigned int initval, int flags);  

L'argument flags n'est actuellement pas utilisé et doit être spécifié à zéro. Dans le futur, il pourrait être utilisé pour des fonctionnalités supplémentaires.

Comme valeur de retour, eventfd() renvoie un nouveau descripteur de fichiers qui peut être utilisé pour faire référence à l'objet eventfd. Les opérations suivantes peuvent être effectuées sur le descripteur de fichiers :

read(2)

Si le compteur eventfd a une valeur non nulle, read(2) renvoie 8 octets qui contiennent cette valeur et la valeur du compteur est réinitialisée à zéro. (La valeur renvoyée est dans l'ordre d'octet de l'hôte, c'est-à-dire l'ordre natif d'octet pour les entiers sur la machine hôte.)

Si le compteur vaut zéro au moment de l'appel à read(2), l'appel soit bloquera jusqu'à ce que le compteur ne soit plus nul, soit échouera avec l'erreur EAGAIN si le descripteur de fichiers était non bloquant (via l'utilisation de l'opération F_SETFL de fcntl(2) pour définir l'attribut O_NONBLOCK).

Un read(2) échouera avec l'erreur EINVAL si la taille du tampon fourni est inférieure à 8 octets.

write(2)

Un appel à write(2) ajoute au compteur la valeur entière sur 8 octets fournie dans son tampon. La valeur maximum qui puisse être stockée dans le compteur est la plus grande valeur 64 bits non signée moins 1 (c'est-à-dire, 0xfffffffffffffffe). Si l'addition fait que la valeur du compteur dépasse le maximum, l'appel à write(2) soit bloquera jusqu'à ce qu'un read(2) soit effectué sur le descripteur de fichiers, soit échouera avec l'erreur EAGAIN si le descripteur de fichiers était non bloquant.

Un write(2) échouera avec l'erreur EINVAL si la taille du tampon fourni est inférieure à 8 octets ou si on essaie d'écrire la valeur 0xffffffffffffffff.

poll(2), select(2) (et semblables)

Le descripteur de fichiers renvoyé prend en charge poll(2) (et par analogie epoll(7)) et select(2), de la manière suivante :

*

Le descripteur de fichiers est accessible en lecture (l'argument readfds de select(2) ; l'attribut POLLIN de poll(2)) si le compteur à une valeur supérieure à 0.

*

Le descripteur de fichiers est accessible en écriture (l'argument writefds de select(2) ; l'attribut POLLOUT de poll(2)) s'il est possible d'écrire une valeur d'au moins « 1 » sans bloquer.

*

Le descripteur de fichiers indique une condition exceptionnelle (l'argument exceptfds select(2) ; l'attribut POLLERR de poll(2)) si un débordement du compteur est détecté. Comme indiqué plus haut, write(2) ne peut jamais faire déborder le compteur. Toutefois, un débordement peut survenir si 2^64 « envois de signaux » eventfd étaient effectués par le sous-sytème KAIO (théoriquement possible, pratiquement improbable). Si un débordement survient, read(2) renverra la valeur uint64_t maximum (c'est-à-dire, 0xffffffffffffffff).

Le descripteur de fichiers eventfd accepte également les autres API de multiplexage de descripteur de fichiers : pselect(2), ppoll(2), and epoll(7).

close(2)

Lorsque le descripteur de fichiers n'est plus nécessaire, il devrait être fermé. Lorsque tous les descripteurs de fichiers associés au même objet eventfd ont été fermés, les ressources pour l'objet sont libérées par le noyau.

Une copie du descripteur de fichiers créé par eventfd() est hérité par le fils produit par fork(2). Le descripteur de fichiers dupliqué est associé au même objet eventfd. Les descripteurs de fichiers créés par eventfd() sont préservés à travers un execve(2).  

EINVAL

flags n'est pas nul.

EMFILE

La limite par processus des descripteurs de fichiers ouverts a été atteinte.

ENFILE

La limite à l'échelle du système du nombre total de fichiers ouverts a été atteinte.

ENODEV

Impossible de monter le périphérique anonyme inode (interne).

ENOMEM

Il n'y a pas suffisamment de mémoire pour créer un nouveau descripteur de fichiers eventfd.

Le temps d'inactivité noyau (Ndt : kernel overhead) d'un descripteur de fichiers est plus court que celui d'un tube et seulement un descripteur de fichiers est nécessaire (contrairement aux deux nécessaires pour un tube).

Lorsqu'il est utilisé dans le noyau, un descripteur de fichiers eventfd peut fournir un pont entre le noyau et l'espace utilisateur permettant, par exemple, à des fonctionnalités comme KAIO (kernel AIO) de signaler à un descripteur de fichiers que certaines opérations sont achevées.

Un point clé à propos des descripteurs de fichiers est qu'ils peuvent être surveillés comme tout autre descripteur de fichiers avec select(2), poll(2) ou epoll(7). Cela signifie qu'une application peut surveiller simultanément la disponibilité de fichiers « traditionnels » et la disponibilité d'autres mécanismes du noyau qui prennent en charge l'interface eventfd. (Sans l'interface eventfd(), ces mécanismes ne pourraient pas être multiplexés via select(2), poll(2) ou epoll(7).)

L'argument flags est un ajout de la glibc à l'appel système sous-jacent qui ne prend que l'argument initval.  

typedef uint64_t eventfd_t;

int eventfd_read(int __fd, eventfd_t *__value);
int eventfd_write(int __fd, eventfd_t value);

Les fonctions effectuent des opérations de lecture et d'écriture sur un descripteur de fichiers, renvoyant 0 si le nombre correct d'octets a été transféré ou -1 autrement.  

Le programme suivant crée un descripteur de fichier et se clone pour créer un processus fils. Pendant que le parent sommeille brièvement, le fils écrit chacun des entiers fournis dans les arguments de la ligne de commande du programme dans le descripteur de fichiers eventfd. Lorsque le parent sort de son sommeil, il lit le descripteur de fichiers eventfd.

La session shell suivante montre un exemple de l'exécution du programme :

$ ./a.out 1 2 4 7 14
Child writing 1 to efd
Child writing 2 to efd
Child writing 4 to efd
Child writing 7 to efd
Child writing 14 to efd
Child completed write loop
Parent about to read
Parent read 28 (0x1c) from efd

#include <sys/eventfd.h>
#include <unistd.h>
#include <stdlib.h>
#include <stdio.h>
#include <stdint.h>             /* Definition of uint64_t */

#define handle_error(msg) \
    do { perror(msg); exit(EXIT_FAILURE); } while (0)

int
main(int argc, char *argv[])
{
    int efd, j;
    uint64_t u;
    ssize_t s;

    if (argc < 2) {
        fprintf(stderr, "Usage: %s <num>...\n", argv[0]);
        exit(EXIT_FAILURE);
    }

    efd = eventfd(0, 0);
    if (efd == -1)
        handle_error("eventfd");

    switch (fork()) {
    case 0:
        for (j = 1; j < argc; j++) {
            printf("Child writing %s to efd\n", argv[j]);
            u = strtoull(argv[j], NULL, 0);
                    /* strtoull() allows various bases */
            s = write(efd, &u, sizeof(uint64_t));
            if (s != sizeof(uint64_t))
                handle_error("write");
        }
        printf("Child completed write loop\n");

        exit(EXIT_SUCCESS);

    default:
        sleep(2);

        printf("Parent about to read\n");
        s = read(efd, &u, sizeof(uint64_t));
        if (s != sizeof(uint64_t))
            handle_error("read");
        printf("Parent read %llu (0x%llx) from efd\n",
                (unsigned long long) u, (unsigned long long) u);
        exit(EXIT_SUCCESS);

    case -1:
        handle_error("fork");
    }
}

Ce document est une traduction réalisée par Alain Portal <aportal AT univ-montp2 DOT fr> le 23 avril 2008 et révisée le 24 avril 2008.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 2 eventfd ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.

NOM

SYNOPSIS

DESCRIPTION

VALEUR RENVOYÉE

ERREURS

VERSIONS

CONFORMITÉ

NOTES

Fonctionnalités supplémentaires de la glibc

EXEMPLE

VOIR AUSSI

TRADUCTION