clock_getres(2) System Calls Manual clock_getres(2) NOM clock_getres, clock_gettime, clock_settime - Fonctions d'horloge et de temps BIBLIOTHEQUE Bibliotheque C standard (libc, -lc), depuis la glibc 2.17 Avant la glibc 2.17, bibliotheque de temps reel (librt, -lrt) SYNOPSIS #include int clock_getres(clockid_t clockid, struct timespec *_Nullable res); int clock_gettime(clockid_t clockid, struct timespec *tp); int clock_settime(clockid_t clockid, const struct timespec *tp); Exigences de macros de test de fonctionnalites pour la glibc (consulter feature_test_macros(7)) : clock_getres(), clock_gettime(), clock_settime() : _POSIX_C_SOURCE >= 199309L DESCRIPTION La fonction clock_getres() cherche la resolution (precision) de l'horloge clockid specifiee et si res est non NULL, elle l'enregistre dans la structure timespec pointee par res. La resolution des horloges depend de l'implementation et ne peut pas etre configuree par un processus particulier. Si la valeur du temps pointe par l'argument tp de clock_settime() n'est pas un multiple de res, cette valeur est tronquee a un multiple de res. Les fonctions clock_gettime() et clock_settime() recuperent et configurent le temps de l'horloge clockid specifiee. Les arguments res et tp sont des structures timespec(3). L'argument clockid est l'identifiant d'une horloge particuliere sur laquelle agir. Une horloge peut etre globale au systeme, et par consequent visible de tous les processus, ou propre a un processus, si elle mesure le temps uniquement pour celui-ci. Toutes les implementations prennent en charge l'horloge temps reel globale, laquelle est identifiee par CLOCK_REALTIME. Son temps represente le nombre de secondes et nanosecondes ecoulees depuis l'epoque UNIX (1er janvier 1970 a 00:00:00 UTC). Lorsque son temps est modifie, les horloges mesurant un intervalle de temps ne sont pas affectees alors que celles indiquant une date (heure) absolue le sont. Plusieurs horloges peuvent etre implementees. L'interpretation des valeurs de temps correspondantes et l'effet sur les temporisateurs ne sont pas specifies. Les versions suffisamment recentes de la glibc et du noyau Linux gerent les horloges suivantes : CLOCK_REALTIME Horloge systeme reglable qui mesure le temps reel (c'est-a-dire comme une pendule). Modifier cette horloge necessite des privileges adequats. Cette horloge est concernee par les sauts discontinus de l'heure systeme (par exemple si l'administrateur modifie l'heure lui-meme), et par les ajustements de frequence effectues par NTP et les applications similaires au moyen d'adjtime(3), adjtimex(2), clock_adjtime(2) et ntp_adjtime(3). Cette horloge compte normallement le nombre de secondes depuis 1970-01-01 00:00:00 UTC (Coordinated Universal Time) sauf qu'elle ignore les secondes intercalaires ; environ une seconde intercalaires est habituellement ajustee par NTP pour rester grossierement synchrone avec l'UTC. CLOCK_REALTIME_ALARM (depuis Linux 3.0 ; specifique a Linux) Comme CLOCK_REALTIME, mais non reglable. Voir timer_create(2) pour plus de details. CLOCK_REALTIME_COARSE (depuis Linux 2.6.32 ; specifique a Linux) Horloge plus rapide mais moins precise que CLOCK_REALTIME. Cette horloge n'est pas reglable. A utiliser pour obtenir rapidement des donnees d'horodatage avec une resolution grossiere. Elle exige une prise en charge specifique a chaque architecture et probablement d'etre prise en charge par une architecture dans vdso(7). CLOCK_TAI (depuis Linux 3.10 ; specifique a Linux) Horloge systeme non reglable derivee d'une pendule mais comptant les secondes intercalaires. Cette horloge ne connait ni discontinuites ni ajustements de frequence suite a des insertions de secondes intercalaires comme le fait CLOCK_REALTIME. L'acronyme TAI renvoie a << International Atomic Time >> (temps international atomique). CLOCK_MONOTONIC Horloge systeme non reglable qui represente le temps monotone depuis -- selon POSIX -- << some unspecified point in the past >> (un point indefini du passe). Sur Linux, ce point correspond au nombre de secondes passees depuis le dernier demarrage du systeme. L'horloge CLOCK_MONOTONIC n'est pas concernee par les sauts discontinus de l'heure systeme (par exemple si l'administrateur modifie l'heure lui-meme), mais est affectee par des ajustements frequence. Cette horloge ne compte pas le temps durant lequel le systeme est en veille. Toutes les variantes de CLOCK_MONOTONIC garantissent que le temps renvoye par des appels consecutifs ne creeront pas de retour en arriere, tandis que les appels successifs -- selon l'architecture -- renvoient des valeurs temporelles identiques (sans augmentation). CLOCK_MONOTONIC_COARSE (depuis Linux 2.6.32 ; specifique a Linux) Horloge plus rapide mais moins precise que CLOCK_MONOTONIC. A utiliser pour obtenir rapidement des donnees d'horodatage avec une resolution grossiere. Elle exige une prise en charge specifique a chaque architecture et probablement d'etre prise en charge par une architecture dans vdso(7). CLOCK_MONOTONIC_RAW (depuis Linux 2.6.28 ; specifique a Linux) Similaire a CLOCK_MONOTONIC, mais fournit un acces direct a un temps materiel qui n'est pas sujet aux ajustements de frequence. Cette horloge ne compte pas le temps durant lequel le systeme est en veille. CLOCK_BOOTTIME (depuis Linux 2.6.39 ; specifique a Linux) Horloge systeme non reglable identique a CLOCK_MONOTONIC, mais qui prend egalement en compte le temps ecoule pendant la veille du systeme. Cela offre aux applications une horloge monotone tenant compte des veilles, sans avoir a s'occuper des problemes de discontinuites de CLOCK_REALTIME si l'horloge est mise a jour avec settimeofday(2) ou equivalent. CLOCK_BOOTTIME_ALARM (depuis Linux 3.0 ; specifique a Linux) Comme CLOCK_BOOTTIME. Voir timer_create(2) pour plus de details. CLOCK_PROCESS_CPUTIME_ID (depuis Linux 2.6.12) Il s'agit d'une horloge qui mesure le temps de processeur consomme par ce processus (a savoir le temps de processeur consomme par tous les threads du processus). Sur Linux, cette horloge n'est pas reglable. CLOCK_THREAD_CPUTIME_ID (depuis Linux 2.6.12) Il s'agit d'une horloge qui mesure le temps de processeur consomme par ce thread. Sur Linux, cette horloge n'est pas reglable. Linux implemente aussi des instances d'horloge dynamique comme decrit ci-dessous. Horloges dynamiques Outre les ID d'horloge a la maniere System-V codes en dur decrits ci-dessus, Linux prend egalement en charge des operations d'horloge POSIX sur certains fichiers de peripheriques. De tels peripheriques s'appellent des << horloges dynamiques >> et ils sont geres depuis Linux 2.6.39. Avec les macros adequates, les descripteurs de fichier ouvert peuvent etre convertis en ID d'horloge et passes a clock_gettime(), clock_settime() et clock_adjtime(2). L'exemple suivant montre la maniere de convertir un descripteur de fichier en ID d'horloge dynamique. #define CLOCKFD 3 #define FD_TO_CLOCKID(fd) ((~(clockid_t) (fd) << 3) | CLOCKFD) #define CLOCKID_TO_FD(clk) ((unsigned int) ~((clk) >> 3)) struct timespec ts; clockid_t clkid; int fd; fd = open("/dev/ptp0", O_RDWR); clkid = FD_TO_CLOCKID(fd); clock_gettime(clkid, &ts); VALEUR RENVOYEE clock_gettime(), clock_settime() et clock_getres() renvoient 0 si elles reussissent. Si elles echouent, -1 est renvoye et errno est positionne pour indiquer l'erreur. ERREURS EACCES clock_settime() n'a pas les droits d'ecriture sur l'horloge POSIX dynamique specifiee. EFAULT tp pointe en dehors de l'espace d'adressage accessible. EINVAL Le clockid indique n'est pas valable pour une ou plusieurs raisons. Soit la valeur positive codee en dur a la maniere de System-V est en dehors de l'intervalle, soit l'ID de l'horloge dynamique ne renvoie pas a une instance valable d'horloge. EINVAL (clock_settime()) : tp.tv_sec est negatif ou tp.tv_nsec depasse la plage [0..999 999 999]. EINVAL La clockid indiquee dans un appel a clock_settime() n'est pas une horloge reglable. EINVAL (depuis Linux 4.3) Un appel a clock_settime() avec un clockid de CLOCK_REALTIME a essaye de positionner l'heure sur une valeur inferieure a celle actuelle de l'horloge CLOCK_MONOTONIC. ENODEV Le peripherique connectable a chaud (comme USB par exemple) represente par un clk_id dynamique a disparu apres que son fichier de peripherique a ete ouvert. ENOTSUP L'operation n'est pas prise en charge par l'horloge POSIX dynamique indiquee. EOVERFLOW L'horodatage ne pouvait pas tenir dans la plage de time_t. Cela se produit si un executable avec time_t en 32 bits est execute sur un noyau 64 bits quand le jour et l'heure sont 03:14:08 UTC le 19 janvier 2038 ou apres. Neanmoins, quand l'horloge systeme est en dehors de la plage de time_t dans d'autres situation, le comportement n'est pas defini. EPERM clock_settime() n'a pas l'autorisation de configurer l'horloge specifiee. ATTRIBUTS Pour une explication des termes utilises dans cette section, consulter attributes(7). +---------------------------------+--------------------------+---------+ |Interface | Attribut | Valeur | +---------------------------------+--------------------------+---------+ |clock_getres(), clock_gettime(), | Securite des threads | MT-Safe | |clock_settime() | | | +---------------------------------+--------------------------+---------+ VERSIONS POSIX.1 specifie ce qui suit : Configurer la valeur de l'horloge CLOCK_REALTIME avec clock_settime(2) ne doit avoir d'effet ni sur les threads bloques attendant un service de temps relatif base sur cette horloge, y compris la fonction nanosleep() ; ni sur l'expiration des compteurs relatifs bases sur cette horloge. En consequence, ces services de temps doivent expirer lorsque la duree relative demandee est atteinte, independamment de l'ancienne ou la nouvelle valeur de l'horloge. Selon POSIX.1-2001, un processus avec des << privileges adequats >> peut changer les horloges CLOCK_PROCESS_CPUTIME_ID et CLOCK_THREAD_CPUTIME_ID avec clock_settime(). Sous Linux, ces horloges ne peuvent pas etre modifiees (c'est-a-dire qu'aucun processus n'a de << privileges adequats >>). Differences entre bibliotheque C et noyau Sur certaines architectures; une implementation de clock_gettime() est fournie dans le vdso(7). STANDARDS POSIX.1-2008. HISTORIQUE POSIX.1-2001, SUSv2. Linux 2.6. Sur les systemes conformes a la specification POSIX sur lesquels ces fonctions sont disponibles, la constante symbolique _POSIX_TIMERS est definie dans comme etant une valeur superieure a 0. Les constantes symboliques _POSIX_MONOTONIC_CLOCK, _POSIX_CPUTIME, _POSIX_THREAD_CPUTIME indiquent que CLOCK_MONOTONIC, CLOCK_PROCESS_CPUTIME_ID, CLOCK_THREAD_CPUTIME_ID sont disponibles. (Consultez aussi sysconf(3).) POSIX.1-2008 rend ces API obligatoires Note historique pour les systemes multiprocesseurs (SMP) Avant la prise en charge par le noyau Linux de CLOCK_PROCESS_CPUTIME_ID et CLOCK_THREAD_CPUTIME_ID, la glibc a mis en oeuvre ces horloges sur bien des plate-formes en utilisant les registres temporisateurs des CPU (TSC sur i386, AR.ITC sur Itanium). Les registres peuvent etre differents entre les CPU avec pour consequence des resultats bidons pour ces horloges si un processus a ete transfere sur un autre CPU. Si les CPU d'un systeme multiprocesseur ont differentes sources d'horloges, il n'y a aucun moyen de maintenir une correlation entre les registres temporisateurs puisque chaque CPU tournera a une frequence legerement differente. Si c'est le cas, clock_getcpuclockid(0) renverra ENOENT pour signifier cette condition. Les deux horloges seront donc utiles si on peut etre certain que le processus reste sur un CPU en particulier. Les processeurs d'un systeme multiprocesseur ne demarrent pas exactement au meme moment, ainsi les registres temporisateurs sont lances avec un decalage. Certaines architectures incluent un code pour tenter de limiter ce decalage au demarrage. Toutefois, ce code ne garantit pas l'accord precis des decalages. La glibc ne contient rien pour gerer ces decalages (a la difference du noyau Linux). Typiquement, ces decalages sont petits et ainsi, leurs effets peuvent etre negligeables dans la plupart des cas. Depuis la glibc 2.4, les fonctions qui encapsulent les appels systeme decrits dans cette page permettent d'eviter les problemes mentionnes ci-dessus en utilisant les horloges CLOCK_PROCESS_CPUTIME_ID et CLOCK_THREAD_CPUTIME_ID du noyau, lorsque celles-ci sont disponibles (c'est-a-dire les versions de Linux 2.6.12 et ulterieures). EXEMPLES Le programme ci-dessous montre l'utilisation de clock_gettime() et de clock_getres() avec differentes horloges. Il s'agit d'un exemple de ce qu'on pourrait voir en lancant le programme : $ ./clock_times x CLOCK_REALTIME : 1585985459.446 (18356 days + 7h 30m 59s) resolution : 0.000000001 CLOCK_TAI : 1585985496.447 (18356 days + 7h 31m 36s) resolution : 0.000000001 CLOCK_MONOTONIC : 52395.722 (14h 33m 15s) resolution : 0.000000001 CLOCK_BOOTTIME : 72691.019 (20h 11m 31s) resolution : 0.000000001 Source du programme /* clock_times.c Sous licence GNU General Public v2 ou posterieure. */ #define _XOPEN_SOURCE 600 #include #include #include #include #include #define SECS_IN_DAY (24 * 60 * 60) static void displayClock(clockid_t clock, const char *name, bool showRes) { long days; struct timespec ts; if (clock_gettime(clock, &ts) == -1) { perror("clock_gettime"); exit(EXIT_FAILURE); } printf("%-15s: %10jd.%03ld (", name, (intmax_t) ts.tv_sec, ts.tv_nsec / 1000000); days = ts.tv_sec / SECS_IN_DAY; if (days > 0) printf("%ld days + ", days); printf("%2dh %2dm %2ds", (int) (ts.tv_sec % SECS_IN_DAY) / 3600, (int) (ts.tv_sec % 3600) / 60, (int) ts.tv_sec % 60); printf(")\n"); if (clock_getres(clock, &ts) == -1) { perror("clock_getres"); exit(EXIT_FAILURE); } if (showRes) printf(" resolution : %10jd.%09ld\n", (intmax_t) ts.tv_sec, ts.tv_nsec); } int main(int argc, char *argv[]) { bool showRes = argc > 1; displayClock(CLOCK_REALTIME, "CLOCK_REALTIME", showRes); #ifdef CLOCK_TAI displayClock(CLOCK_TAI, "CLOCK_TAI", showRes); #endif displayClock(CLOCK_MONOTONIC, "CLOCK_MONOTONIC", showRes); #ifdef CLOCK_BOOTTIME displayClock(CLOCK_BOOTTIME, "CLOCK_BOOTTIME", showRes); #endif exit(EXIT_SUCCESS); } VOIR AUSSI date(1), gettimeofday(2), settimeofday(2), time(2), adjtime(3), clock_getcpuclockid(3), ctime(3), ftime(3), pthread_getcpuclockid(3), sysconf(3), timespec(3), time(7), time_namespaces(7), vdso(7), hwclock(8) TRADUCTION La traduction francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot et Jean-Philippe MENGUAL Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.06 11 novembre 2023 clock_getres(2)