.\" -*- coding: UTF-8 -*- .\" Copyright (C) 2008 Michael Kerrisk .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH timerfd_create 2 "2 mai 2024" "Pages du manuel de Linux 6.8" .SH NOM timerfd_create, timerfd_settime, timerfd_gettime \- Minuteries qui informent par l'intermédiaire de descripteurs de fichier .SH BIBLIOTHÈQUE Bibliothèque C standard (\fIlibc\fP, \fI\-lc\fP) .SH SYNOPSIS .nf \fB#include \fP .P \fBint timerfd_create(int \fP\fIclockid\fP\fB, int \fP\fIflags\fP\fB);\fP .P \fBint timerfd_settime(int \fP\fIfd\fP\fB, int \fP\fIflags\fP\fB,\fP \fB const struct itimerspec *\fP\fInew_value\fP\fB,\fP \fB struct itimerspec *_Nullable \fP\fIold_value\fP\fB);\fP \fBint timerfd_gettime(int \fP\fIfd\fP\fB, struct itimerspec *\fP\fIcurr_value\fP\fB);\fP .fi .SH DESCRIPTION Ces appels système créent et opèrent sur une minuterie qui fournit des notifications d'expiration par un descripteur de fichier. Ils fournissent une alternative à \fBsetitimer\fP(2) ou \fBtimer_create\fP(2) avec l'avantage que le descripteur de fichier peut être surveillé avec \fBselect\fP(2), \fBpoll\fP(2) ou \fBepoll\fP(7). .P .\" L'utilisation de ces trois appels système est analogue à l'utilisation de \fBtimer_create\fP(2), \fBtimer_settime\fP(2) et \fBtimer_gettime\fP(2). (Il n'y a pas d'équivalent à \fBtimer_getoverrun\fP(2) puisque cette fonctionnalité est fournie par \fBread\fP(2), comme décrit ci\-dessous) .SS timerfd_create() \fBtimerfd_create\fP() crée un nouvel objet minuterie et renvoie un descripteur de fichier qui se réfère à cette minuterie. Le paramètre \fIclockid\fP indique l'horloge utilisée pour marquer la progression de la minuterie qui doit être une des suivantes : .TP \fBCLOCK_REALTIME\fP Une horloge temps réel configurable à l'échelle du système. .TP \fBCLOCK_MONOTONIC\fP Une horloge non configurable, toujours croissante qui mesure le temps depuis un instant non spécifié dans le passé et qui ne change pas après le démarrage du système. .TP \fBCLOCK_BOOTTIME\fP (depuis Linux 3.15) .\" commit 4a2378a943f09907fb1ae35c15de917f60289c14 C'est une horloge toujours croissante comme \fBCLOCK_MONOTONIC\fP. Cependant alors que l'horloge \fBCLOCK_MONOTONIC\fP ne mesure pas le temps aussi longtemps que le système est suspendu, l'horloge \fBCLOCK_BOOTTIME\fP inclut le temps pendant lequel le système est suspendu. Cela est utile pour les applications qui doivent être sensibles au temps de suspension. \fBCLOCK_REALTIME\fP n'est pas adapté à ce type d'application dans la mesure où cette horloge est affectée par des modifications discontinues de l'horloge système. .TP \fBCLOCK_REALTIME_ALARM\fP (depuis Linux 3.11) .\" commit 11ffa9d6065f344a9bd769a2452f26f2f671e5f8 Cette horloge se comporte comme \fBCLOCK_REALTIME\fP, mais réveillera le système s'il est suspendu. L'appelant doit avoir la capacité \fBCAP_WAKE_ALARM\fP afin de régler une minuterie utilisant cette horloge. .TP \fBCLOCK_BOOTTIME_ALARM\fP (depuis Linux 3.11) .\" commit 11ffa9d6065f344a9bd769a2452f26f2f671e5f8 Cette horloge se comporte comme \fBCLOCK_BOOTTIME\fP, mais réveillera le système s'il est suspendu. L'appelant doit avoir la capacité \fBCAP_WAKE_ALARM\fP afin de régler une minuterie utilisant cette horloge. .P Consultez \fBclock_getres\fP(2) pour quelques détails supplémentaires sur les horloges mentionnées. .P La valeur actuelle de chacune de ces horloges peut être obtenue avec \fBclock_gettime\fP(2). .P À partir de Linux 2.6.27, les valeurs suivantes peuvent être incluses avec un OU binaire dans \fIflags\fP pour changer le comportement de \fBtimerfd_create\fP() : .TP 14 \fBTFD_NONBLOCK\fP Placer l'attribut d'état de fichier \fBO_NONBLOCK\fP sur la description du fichier ouvert référencée par le nouveau descripteur de fichier (consulter \fBopen\fP(2)). Utiliser cet attribut économise des appels supplémentaires à \fBfcntl\fP(2) pour obtenir le même résultat. .TP \fBTFD_CLOEXEC\fP Placer l'attribut « close\-on\-exec » (\fBFD_CLOEXEC\fP) sur le nouveau descripteur de fichier. Consultez la description de l'attribut \fBO_CLOEXEC\fP dans \fBopen\fP(2) pour savoir pourquoi cela peut être utile. .P Dans les versions de Linux jusqu'à la version 2.6.26 incluse, \fIflags\fP doit être nul. .SS timerfd_settime() \fBtimerfd_settime\fP() arme (démarre) ou désarme (stoppe) la minuterie à laquelle se réfère le descripteur de fichier \fIfd\fP. .P Le paramètre \fInew_value\fP spécifie l'expiration initiale et l'intervalle de la minuterie. La structure \fIitimerspec\fP utilisée pour ce paramètre est décrite dans \fIitimerspec\fP(3type) : .P \fInew_value.it_value\fP spécifie l'expiration initiale de la minuterie, en secondes et nanosecondes. Une valeur non nulle dans un des champs de \fInew_value.it_value\fP arme la minuterie. La minuterie est désarmée si les deux champs de \fInew_value.it_value\fP sont mis à zéro. .P Une valeur non nulle dans un des champs de \fInew_value.it_interval\fP configure la période, en secondes et nanosecondes, pour une expiration répétitive après l'expiration initiale. Si les deux champs de \fInew_value.it_interval\fP sont nuls, la minuterie expirera qu'une seule fois, dont l'heure est spécifiée dans \fInew_value.it_value\fP. .P Par défaut, l'heure d'expiration initiale spécifiée dans \fInew_value\fP est interprétée de façon relative par rapport à l'heure actuelle sur l'horloge de la minuterie au moment de l'appel (c'est\-à\-dire que \fInew_value.it_value\fP indique une heure relative à la valeur actuelle de l'horloge spécifiée par \fIclockid\fP). Un délai absolu peut être sélectionné avec le paramètre \fIflags\fP. .P Le paramètre \fIflags\fP est un masque de bits qui peut avoir les valeurs suivantes : .TP \fBTFD_TIMER_ABSTIME\fP Interpréter \fInew_value.it_value\fP comme une valeur absolue sur l'horloge de la minuterie. La minuterie expirera quand la valeur de l'horloge de la minuterie atteint la valeur spécifiée dans \fInew_value.it_value\fP. .TP \fBTFD_TIMER_CANCEL_ON_SET\fP Si cet attribut est spécifié en même temps que \fBTFD_TIMER_ABSTIME\fP et si l'horloge pour cette minuterie est \fBCLOCK_REALTIME\fP ou \fBCLOCK_REALTIME_ALARM\fP, alors marquer cette minuterie comme annulable si l'horloge en temps réel subit une modification discontinue (\fBsettimeofday\fP(2), \fBclock_settime\fP(2) ou similaire). Quand des modifications se produisent, un appel actuel ou futur à \fBread\fP(2) à partir du descripteur de fichier échouera avec l’erreur \fBECANCELED\fP. .P .\" Si le paramètre \fIold_value\fP n'est pas égal à NULL, la structure \fIitimerspec\fP vers laquelle il pointe est utilisée pour renvoyer la configuration de la minuterie au moment de l'appel ; consultez la description de \fBtimerfd_gettime\fP() ci\-dessous. .SS timerfd_gettime() \fBtimerfd_gettime\fP() renvoie, dans \fIcurr_value\fP, une structure \fIitimerspec\fP qui contient les paramètres actuels de la minuterie auquel le descripteur de fichier \fIfd\fP fait référence. .P Le champ \fIit_value\fP renvoie la durée jusqu'à la prochaine expiration. Si les deux champs de cette structure sont nuls, alors la minuterie est actuellement désactivée. Ce champ contient toujours une valeur relative, sans tenir compte d'un attribut \fBTFD_TIMER_ABSTIME\fP qui aurait été spécifié quand la minuterie a été configurée. .P Le champ \fIit_interval\fP renvoie l'intervalle de la minuterie. Si les deux champs de cette structure sont nuls, alors la minuteries est configurée pour n'expirer qu'une seule fois, à l'heure spécifiée par \fIcurr_value.it_value\fP. .SS "Opérations sur un descripteur de fichier de minuterie" Le descripteur de fichier renvoyé par \fBtimerfd_create\fP() gère les opérations supplémentaires suivantes : .TP \fBread\fP(2) Si la minuterie a déjà expirée une fois ou plus depuis que sa configuration a été modifiée la dernière fois à l'aide de \fBtimerfd_settime\fP() ou depuis la dernière lecture avec \fBread\fP(2) qui a réussi, alors le tampon fourni à \fBread\fP(2) renvoie un entier non signé sur 8 octets (\fIuint64_t\fP) qui contient le nombre d'expirations qui se sont produites. (La valeur renvoyée 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.) .IP Si aucune expiration ne s'est produite au moment de l'appel à \fBread\fP(2), l'appel bloquera jusqu'à la prochaine expiration ou échouera avec l'erreur \fBEAGAIN\fP si le descripteur de fichier est en mode non bloquant (à l'aide de de l'opération \fBF_SETFL\fP de \fBfcntl\fP(2) pour régler l'attribut \fBO_NONBLOCK\fP). .IP Un \fBread\fP(2) échouera avec l'erreur \fBEINVAL\fP si la taille du tampon fourni est de moins de 8 octets. .IP Si l'horloge associée est soit \fBCLOCK_REALTIME\fP ou \fBCLOCK_REALTIME_ALARM\fP, si la minuterie est absolue (\fBTFD_TIMER_ABSTIME\fP) et si l'attribut \fBTFD_TIMER_CANCEL_ON_SET\fP a été spécifié lors de l'appel \fBtimerfd_settime\fP(), alors l'appel à \fBread\fP(2) échoue avec l'erreur \fBECANCELED\fP si l'horloge en temps réel subit une modification discontinue. (Cela permet à l'application qui lit de découvrir ce type de modifications discontinues à l'horloge.) .IP Si l'horloge associée est soit \fBCLOCK_REALTIME\fP ou \fBCLOCK_REALTIME_ALARM\fP, si la minuterie est absolue (\fBTFD_TIMER_ABSTIME\fP) et si l'attribut \fBTFD_TIMER_CANCEL_ON_SET\fP a été spécifié lors de l'appel \fBtimerfd_settime\fP(), alors une modification négative discontinue à l'horloge (par exemple, \fBclock_settime\fP(2)) peut faire à que \fBread\fP(2) supprime le blocage, mais renvoie une valeur de \fB0\fP (c'est\-à\-dire qu'aucun octet n'est lu), si une modification d'horloge survient après que le temps soit expiré, mais avant le \fBread\fP(2) sur le descripteur de fichier. .TP \fBpoll\fP(2) .TQ \fBselect\fP(2) .TQ (et similaire) Le descripteur de fichier est lisible (le paramètre \fIreadfds\fP de \fBselect\fP(2) ; l'attribut \fBPOLLIN\fP de \fBpoll\fP(2)) si une expiration (ou plus) de la minuterie s'est produite. .IP Le descripteur de fichier prend également en charge les autres interfaces de multiplexage de descripteurs de fichier : \fBpselect\fP(2), \fBppoll\fP(2) et \fBepoll\fP(7). .TP \fBioctl\fP(2) La commande suivante spécifique à timerfd est prise en charge : .RS .TP \fBTFD_IOC_SET_TICKS\fP (depuis Linux 3.17) .\" commit 5442e9fbd7c23172a1c9bc736629cd123a9923f0 Ajuste le nombre d'expirations de minuterie qui sont survenues. Le paramètre est un pointeur vers un entier de 8 octets différent de zéro (\fIuint64_t\fP*) contenant le nouveau nombre d'expirations. Une fois que le nombre est défini, tout processus en attente de la minuterie est réveillé. Le seul objectif de cette commande est de rétablir les expirations dans l'objectif de points de vérification ou de restauration. Cette opération est disponible seulement si le noyau a été configuré avec l'option \fBCONFIG_CHECKPOINT_RESTORE\fP. .RE .TP \fBclose\fP(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 minuterie ont été fermés, la minuterie est désarmée et ses ressources sont libérées par le noyau. .SS "Sémantique de \fBfork\fP(2)" .\" Après un \fBfork\fP(2), l'enfant hérite d'une copie du descripteur de fichier créé par \fBtimerfd_create\fP(). Le descripteur de fichier se réfère au même objet minuterie sous\-jacent que le descripteur de fichier correspondant dans le parent, et un \fBread\fP(2) de l'enfant renverra les informations sur les expirations de la minuterie. .SS "Sémantique de \fBexecve\fP(2)" Un descripteur de fichier créé par \fBtimerfd_create\fP() est conservé au travers d'un \fBexecve\fP(2), et continue à générer des expirations de minuterie si la minuterie a été armée. .SH "VALEUR RENVOYÉE" S'il réussit, \fBtimerfd_create\fP() renvoie un nouveau descripteur de fichier. En cas d'erreur, il renvoie \fB\-1\fP et \fIerrno\fP est défini pour indiquer l'erreur. .P En cas de réussite, \fBtimerfd_settime\fP() et \fBtimerfd_gettime\fP() renvoient \fB0\fP. Sinon ils renvoient \fB\-1\fP et définissent \fBerrno\fP pour indiquer l'erreur. .SH ERREURS \fBtimerfd_create\fP() peut échouer avec les erreurs suivantes : .TP \fBEINVAL\fP Le \fIclockid\fP n'est pas valable. .TP \fBEINVAL\fP \fIflags\fP n'est pas correct ; ou, pour les versions de Linux 2.6.26 ou antérieures, \fIflags\fP n'est pas nul. .TP \fBEMFILE\fP La limite du nombre de descripteurs de fichiers par processus a été atteinte. .TP \fBENFILE\fP La limite du nombre total de fichiers ouverts pour le système entier a été atteinte. .TP \fBENODEV\fP Impossible de monter (en interne) le périphérique anonyme d'inœud. .TP \fBENOMEM\fP Pas assez de mémoire noyau pour créer la minuterie. .TP \fBEPERM\fP \fIclockid\fP était \fBCLOCK_REALTIME_ALARM\fP ou \fBCLOCK_BOOTTIME_ALARM\fP, mais l'appelant n'a pas la capacité \fBCAP_WAKE_ALARM\fP. .P \fBtimerfd_settime\fP() et \fBtimerfd_gettime\fP() peuvent échouer avec les erreurs suivantes : .TP \fBEBADF\fP \fIfd\fP n'est pas un descripteur de fichier valable. .TP \fBEFAULT\fP \fInew_value\fP, \fIold_value\fP ou \fIcurr_value\fP n'est pas un pointeur valable. .TP \fBEINVAL\fP \fIfd\fP n'est pas un descripteur de fichier de minuterie valable. .P \fBtimerfd_settime\fP() peut aussi échouer avec les erreurs suivantes : .TP \fBECANCELED\fP Voir NOTES .TP \fBEINVAL\fP \fInew_value\fP n'est pas initialisé correctement (un des champs \fItv_nsec\fP est en dehors de l'intervalle allant de 0 à 999 999 999). .TP \fBEINVAL\fP .\" This case only checked since Linux 2.6.29, and Linux 2.2.2[78].some-stable-version. .\" In older kernel versions, no check was made for invalid flags. \fIflags\fP n'est pas correct. .SH STANDARDS Linux. .SH HISTORIQUE Linux 2.6.25, glibc 2.8. .SH NOTES En supposant le scénario suivant pour une minuterie \fBCLOCK_REALTIME\fP ou \fBCLOCK_REALTIME_ALARM\fP créée avec \fBtimerfd_create\fP() : .IP (1) 5 la minuterie a été démarrée (\fBtimerfd_settime\fP()) avec les attributs \fBTFD_TIMER_ABSTIME\fP et \fBTFD_TIMER_CANCEL_ON_SET\fP ; .IP (2) une modification discontinue (par exemple, \fBsettimeofday\fP(2)) est ensuite appliquée à l'horloge \fBCLOCK_REALTIME\fP ; .IP (3) l'appelant appelle une fois de plus \fBtimerfd_settime\fP() pour réarmer la minuterie (sans exécuter préalablement un \fBread\fP(2) sur le descripteur de fichier). .P Dans ce cas les événements suivants se produisent : .IP \- 3 \fBtimerfd_settime\fP() renvoie \fB\-1\fP avec \fIerrno\fP défini à \fBECANCELED\fP. (Cela permet à l'appelant de savoir que la minuterie précédente a été affectée par une modification discontinue de l'horloge.) .IP \- La minuterie \fIest réarmée avec succès\fP avec les réglages fournis dans le second appel \fBtimerfd_settime\fP(). (C'est probablement un accident d'implémentation, mais ne sera pas corrigé maintenant au cas où des applications dépendent de ce comportement.) .SH BOGUES .\" 2.6.29 Actuellement, \fBtimerfd_create\fP() prend en charge moins de types d'identifiant d'horloges que \fBtimer_create\fP(2). .SH EXEMPLES Le programme suivant crée une minuterie puis surveille sa progression. Le programme accepte jusqu'à trois paramètres en ligne de commande. Le premier paramètre spécifie le nombre de secondes pour l'expiration initiale de la minuterie. Le deuxième paramètre spécifie l'intervallse de la minuterie, en secondes. Le troisième paramètre spécifie le nombre de fois que le programme doit permettre à la minuterie d'expirer avant de quitter. Le deuxième et le troisième paramètre sont optionnels. .P La session interactive suivante montre l'utilisation de ce programme\ : .P .in +4n .EX $\fB a.out 3 1 100\fP 0.000: timer started 3.000: read: 1; total=1 4.000: read: 1; total=2 \fB\[ha]Z \fP # entrer Ctrl\-Z pour suspendre le programme [1]+ Stopped ./timerfd3_demo 3 1 100 $ \fBfg\fP # Reprendre l'exécution après quelques secondes a.out 3 1 100 9.660: read: 5; total=7 10.000: read: 1; total=8 11.000: read: 1; total=9 \fB\[ha]C \fP # entrer Ctrl\-C pour suspendre le programme .EE .in .SS "Source du programme" .\" SRC BEGIN (timerfd_create.c) \& .EX .\" The commented out code here is what we currently need until .\" the required stuff is in glibc .\" .\" .\"/* Link with \-lrt */ .\"#define _GNU_SOURCE .\"#include .\"#include .\"#include .\"#if defined(__i386__) .\"#define __NR_timerfd_create 322 .\"#define __NR_timerfd_settime 325 .\"#define __NR_timerfd_gettime 326 .\"#endif .\" .\"static int .\"timerfd_create(int clockid, int flags) .\"{ .\" return syscall(__NR_timerfd_create, clockid, flags); .\"} .\" .\"static int .\"timerfd_settime(int fd, int flags, struct itimerspec *new_value, .\" struct itimerspec *curr_value) .\"{ .\" return syscall(__NR_timerfd_settime, fd, flags, new_value, .\" curr_value); .\"} .\" .\"static int .\"timerfd_gettime(int fd, struct itimerspec *curr_value) .\"{ .\" return syscall(__NR_timerfd_gettime, fd, curr_value); .\"} .\" .\"#define TFD_TIMER_ABSTIME (1 << 0) .\" .\"//////////////////////////////////////////////////////////// #include #include #include #include #include #include #include #include \& static void print_elapsed_time(void) { int secs, nsecs; static int first_call = 1; struct timespec curr; static struct timespec start; \& if (first_call) { first_call = 0; if (clock_gettime(CLOCK_MONOTONIC, &start) == \-1) err(EXIT_FAILURE, "clock_gettime"); } \& if (clock_gettime(CLOCK_MONOTONIC, &curr) == \-1) err(EXIT_FAILURE, "clock_gettime"); \& secs = curr.tv_sec \- start.tv_sec; nsecs = curr.tv_nsec \- start.tv_nsec; if (nsecs < 0) { secs\-\-; nsecs += 1000000000; } printf("%d.%03d: ", secs, (nsecs + 500000) / 1000000); } \& int main(int argc, char *argv[]) { int fd; ssize_t s; uint64_t exp, tot_exp, max_exp; struct timespec now; struct itimerspec new_value; \& if (argc != 2 && argc != 4) { fprintf(stderr, "%s init\-secs [interval\-secs max\-exp]\en", argv[0]); exit(EXIT_FAILURE); } \& if (clock_gettime(CLOCK_REALTIME, &now) == \-1) err(EXIT_FAILURE, "clock_gettime"); \& /* Créer une minuterie absolue CLOCK_REALTIME avec une expiration et un intervalle initiaux comme spécifié en ligne de commande. */ \& new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]); new_value.it_value.tv_nsec = now.tv_nsec; if (argc == 2) { new_value.it_interval.tv_sec = 0; max_exp = 1; } else { new_value.it_interval.tv_sec = atoi(argv[2]); max_exp = atoi(argv[3]); } new_value.it_interval.tv_nsec = 0; \& fd = timerfd_create(CLOCK_REALTIME, 0); if (fd == \-1) err(EXIT_FAILURE, "timerfd_create"); \& if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == \-1) err(EXIT_FAILURE, "timerfd_settime"); \& print_elapsed_time(); printf("timer started\en"); \& for (tot_exp = 0; tot_exp < max_exp;) { s = read(fd, &exp, sizeof(uint64_t)); if (s != sizeof(uint64_t)) err(EXIT_FAILURE, "read"); \& tot_exp += exp; print_elapsed_time(); printf("read: %" PRIu64 "; total=%" PRIu64 "\en", exp, tot_exp); } \& exit(EXIT_SUCCESS); } .EE .\" SRC END .SH "VOIR AUSSI" \fBeventfd\fP(2), \fBpoll\fP(2), \fBread\fP(2), \fBselect\fP(2), \fBsetitimer\fP(2), \fBsignalfd\fP(2), \fBtimer_create\fP(2), \fBtimer_gettime\fP(2), \fBtimer_settime\fP(2), \fBtimespec\fP(3), \fBepoll\fP(7), \fBtime\fP(7) .PP .SH TRADUCTION La traduction française de cette page de manuel a été créée par Christophe Blaess , Stéphan Rafin , Thierry Vignaud , François Micaux, Alain Portal , Jean-Philippe Guérard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas François , Florentin Duneau , Simon Paillard , Denis Barbier , David Prévot , Cédric Boutillier , Frédéric Hantrais et Jean-Pierre Giraud . .PP Cette traduction est une documentation libre ; veuillez vous reporter à la .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License version 3 .UE concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE. .PP Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à .MT debian-l10n-french@lists.debian.org .ME .