GETITIMER(2)

NOM
getitimer, setitimer - Lire/écrire la valeur d'une temporisation

SYNOPSIS
#include <sys/time.h>

int getitimer(int which, struct itimerval *curr_value);
int setitimer(int which, const struct itimerval *new_value,
              struct itimerval *old_value);

DESCRIPTION
Le système fournit pour chaque processus trois temporisations, chacune avec un fonctionnement particulier. Lorsqu'une temporisation expire, un signal est envoyé au processus et la temporisation est réinitialisée à l'intervalle spécifié (s'il n'est pas nul).

ITIMER_REAL
    décroît en temps réel et un signal SIGALRM est émis à l'expiration du délai.

ITIMER_VIRTUAL
    décroît uniquement quand le processus s'exécute, et un signal SIGVTALRM est émis à l'expiration du délai.

ITIMER_PROF
    décroît à la fois quand le processus s'exécute, et quand le processeur exécute des fonctions systèmes à la demande du processus. Cette temporisation, utilisée conjointement avec ITIMER_VIRTUAL, est généralement utilisée pour obtenir le profil d'exécution du processus entre les fonctionnalités utilisateur et le noyau. SIGPROF est émis à l'expiration du délai.

Les valeurs des temporisations sont définies avec les structures suivantes :
struct itimerspec {
    struct timespec it_interval;  /* Intervalle pour les
                                     minuteries périodiques */
    struct timespec it_value;     /* Délai jusqu'à la prochaine
                                     expiration */
};
struct timeval {
    time_t tv_sec;                /* secondes        */
    suseconds_t tv_usec;          /* microsecondes   */
};

La fonction getitimer() renseigne la structure pointée par curr_value avec la valeur courante (c'est à dire la quantité de temps restant avant l'expiration suivante) avec le paramétrage de la temporisation indiqué par which (par ITIMER_REAL, ITIMER_VIRTUAL, ou ITIMER_PROF). Les éléments du champ it_value sont remplis avec le délai restant dans la temporisation, ou zéro si la temporisation est désactivée. De même, it_interval sera rempli avec la valeur originale de la temporisation ; lorsqu'une valeur nulle est renvoyée dans les deux éléments du champ, cela signifie que la temporisation est « à un coup » (c'est à dire non périodique). La fonction setitimer() positionne la temporisation avec les valeurs de new_value. Si old_value n'est pas NULL, les paramètres précédents de la temporisation (c'est-à-dire la même information renvoyée par getitimer()) y sont inscrits.

Les temporisations décroissent de it_value à zéro, déclenchent un signal, et sont replacées à it_interval. Une temporisation s'arrête si elle est mise à zéro (it_value vaut zéro) ou bien elle expire et it_interval vaut zéro.

Les deux champs tv_sec et tv_usec sont utilisés pour déterminer la durée d'une temporisation.

Les temporisations n'expirent jamais avant la fin du temps requis, et expirent plutôt avec un court délai après la limite. Ce délai dépend de la résolution de la temporisation système et de la charge du système ; consultez time(7) (mais consultez la section BOGUES ci-dessous). À l'expiration, un signal est déclenché puis la temporisation réinitialisée. Si la temporisation expire alors que le processus est actif (toujours vrai avec ITIMER_VIRTUAL) le signal sera délivré immédiatement. Autrement, il y aura un petit délai avant réception du signal, dépendant de la charge du système.

VALEUR RENVOYÉE
S'il réussit, cet appel système renvoie 0. S'il échoue, il renvoie -1 et remplit errno en conséquence.

ERREURS

EFAULT
    new_value, old_value ou curr_value n'est pas un pointeur valable.

EINVAL
    which n'est ni ITIMER_REAL, ni ITIMER_VIRTUAL, ni ITIMER_PROF ; ou (depuis Linux 2.6.22) un des champs tv_usec dans la structure pointée par new_value contient une valeur hors de l'intervalle 0 à 999 999.

CONFORMITÉ
POSIX.1-2001, SVr4, BSD 4.4 (cet appel est apparu dans BSD 4.2). POSIX.1-2008 marque getitimer() et setitimer() comme étant obsolètes, en recommandant d'utiliser à la place l'API des temporisations POSIX (timer_gettime(2), timer_settime(2), etc.).

NOTES
Un fils créé avec fork(2) n'hérite pas des temporisations périodiques de son père. Les temporisations périodiques sont conservées au travers d'un execve(2). POSIX.1 laisse indéterminées les actions entre setitimer() et les trois interfaces alarm(2), sleep(3) et usleep(3). Les normes ne donnent pas la signification de l'appel :
    setitimer(which, NULL, &old_value); De nombreux systèmes d'exploitation (Solaris, les BSD et peut-être d'autres) le traitent comme étant équivalent à :
    getitimer(which, &old_value); Dans Linux, il est traité comme étant équivalent à un appel dans lequel les champs de new_value sont égaux à zéro, ce qui correspondrait à une temporisation désactivée. N'utilisez pas cette non-fonctionnalité de Linux : elle est non portable et inutile.

BOGUES
Sous Linux, l'émission et la réception d'un signal sont distincts, et un même signal ne peut pas être émis deux fois de suite si le premier n'a pas été reçu. Il est ainsi possible qu'avec une charge système très élevée, une temporisation ITIMER_REAL expire avant que le signal d'une expiration précédente n'ait été reçu. Le second signal sera alors perdu. Sous les noyaux Linux antérieurs au 2.6.16, les valeurs des temporisations sont exprimées en « jiffies ». Si une temporisation est initialisée à une valeur en jiffies dépassant la constante MAX_SEC_IN_JIFFIES (définie dans include/linux/jiffies.h), la temporisation est silencieusement tronquée à cette valeur maximale. Sous Linux sur i386 (où, depuis Linux 2.6.13, un jiffy correspond par défaut à 4 millisecondes), cela signifie que la valeur maximale d'une temporisation est environ 99,42 jours. Depuis Linux 2.6.16, le noyau utilise une représentation interne du temps différente et le plafond est supprimé. Sur certains systèmes (y compris i386), les noyaux Linux avant la version 2.6.12 ont un bogue qui cause des expirations prématurées de temporisation, avec une avance pouvant aller jusqu'à un jiffy dans certaines circonstances. Ce bogue est corrigé dans Linux 2.6.12. Selon POSIX.1-2001, setitimer() devrait échouer si la valeur de tv_usec fournie n'est pas entre 0 et 999999. Cependant, dans les noyaux de version inférieure ou égale à 2.6.21, Linux ne renvoie pas d'erreur, et se contente d'ajuster la valeur de tv_sec correspondante. Depuis le noyau 2.6.22, cette non conformité a été corrigée ; une valeur non valable de tv_usec résulte en une erreur EINVAL.

VOIR AUSSI
gettimeofday(2), sigaction(2), signal(2), timer_create(2), timerfd_create(2), time(7)

COLOPHON
Cette page fait partie de la publication 3.70 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 à <perkamon-fr@traduc.org>.

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