NOM¶

SYNOPSIS¶

int eventfd(unsigned int initval, int flags);

DESCRIPTION¶

Comme valeur de retour, eventfd() renvoie un nouveau descripteur de fichier qui peut être utilisé pour se référer à l'objet eventfd.

Les valeurs suivantes peuvent être incluses (avec un OU logique) dans flags pour changer le comportement de eventfd() :

EFD_CLOEXEC (depuis Linux 2.6.27)

Placer l'attribut « close-on-exec » (FD_CLOEXEC) sur le nouveau descripteur de fichier. Consultez la description de l'attribut O_CLOEXEC dans open(2) pour savoir pourquoi cela peut être utile.

EFD_NONBLOCK (depuis Linux 2.6.27)

Placer l'attribut d'état de fichier O_NONBLOCK sur la description du fichier ouvert référencée par le nouveau descripteur de fichier (consulter open(2)). Utiliser cet attribut économise des appels supplémentaires à fcntl(2) pour obtenir le même résultat.

EFD_SEMAPHORE (depuis Linux 2.6.30)

Fournir une sémantique similaire aux sémaphores pour les lectures sur le nouveau descripteur de fichier. Voir ci-dessous.

Dans les versions de Linux jusqu'à la version 2.6.26, le paramètre flags n'est pas utilisé et doit valoir zéro.

Les opérations suivantes peuvent être effectuées sur le descripteur de fichier renvoyé par eventfd() :

read(2)

Chaque read(2) qui réussit renvoie un entier sur 8 octets. read(2) échouera avec l'erreur EINVAL si la taille du tampon fourni est de moins de 8 octets.

La valeur renvoyée par read(2) utilise l'ordre des octets de l'hôte, c'est-à-dire l'ordre des octets natif pour les entiers sur la machine hôte.

La sémantique de read(2) dépend du fait que le compteur eventfd a actuellement une valeur non nulle, et que l'attribut EFD_SEMAPHORE était spécifié lors de la création du descripteur de fichier eventfd :

write(2)

Un appel à write(2) ajoute au compteur la valeur de l'entier sur 8 octets fourni dans le tampon. La valeur maximale qui peut être stockée dans le compteur est le plus grand entier non signé sur 64 bits moins 1 (c'est-à-dire 0xfffffffffffffffe). Si l'addition résulte en un compteur qui dépasserait la valeur maximale, le write(2) bloquera jusqu'à ce qu'un read(2) soit effectué sur le descripteur de fichier, ou échouera avec l'erreur EAGAIN si le descripteur de fichier est en mode non bloquant.

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

poll(2), select(2) (et similaire)

Le descripteur de fichier prend en charge les poll(2) (et de façon analogue epoll(7)) et select(2) de la façon suivante :

Le descripteur de fichier eventfd prend également en charge les autres interfaces de multiplexage de descripteurs de fichier : pselect(2) et ppoll(2).

close(2)

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

Une copie d'un descripteur de fichier créé par eventfd() est héritée par le fils produit par fork(2). Le duplicata du descripteur de fichier est associé au même objet eventfd. Les descripteurs de fichier créés par eventfd() sont préservés au travers des exécutions par execve(2), sauf si l'attribut « close‐on‐exec » est positionné.

VALEUR RENVOYÉE¶

ERREURS¶

EINVAL

Une valeur non prise en compte a été spécifiée dans flags.

EMFILE

La limite du nombre de descripteurs de fichiers par processus a été atteinte.

ENFILE

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

ENODEV

Impossible de monter (en interne) le périphérique anonyme d'inœud.

ENOMEM

Il n'y a pas assez de mémoire pour que le noyau crée le nouveau descripteur de fichier eventfd.

VERSIONS¶

ATTRIBUTS¶

CONFORMITɶ

NOTES¶

Quand un descripteur de fichier eventfd est utilisé par le noyau, il peut fournir un pont entre l'espace utilisateur et l'espace noyau. Par exemple, les fonctionnalités comme KAIO (« kernel AIO ») pour signaler dans un descripteur de fichier que certaines opérations sont finies.

Un aspect important d'un descripteur de fichier eventfd est qu'il peut être surveillé comme n'importe quel descripteur de fichier avec select(2), poll(2) ou epoll(7). Ceci signifie qu'une application peut surveiller simultanément la disponibilité de fichiers « traditionnels » et la disponibilité de mécanismes noyau qui gèrent une interface eventfd. (Sans l'interface eventfd(), ces mécanismes ne pouvaient pas être multiplexés avec select(2), poll(2) ou epoll(7))

La valeur actuelle d'un compteur eventfd peut être visualisée avec l'entrée du descripteur de fichier correspondant dans le répertoire /proc/[pid]/fdinfo du processus. Voir proc(5) pour plus de détails.

typedef uint64_t eventfd_t;
int eventfd_read(int fd, eventfd_t *value);
int eventfd_write(int fd, eventfd_t value);

EXEMPLE¶

La session shell suivante montre un exemple d'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 de 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");
    }
}

VOIR AUSSI¶

COLOPHON¶

TRADUCTION¶

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à <debian-l10n-french@lists.debian.org>.