rtc(4) Device Drivers Manual rtc(4) NOM rtc - Horloge temps reel SYNOPSIS #include int ioctl(fd, RTC_request, param); DESCRIPTION Il s'agit d'une interface aux pilotes pour les horloges temps reel (RTC). La plupart des ordinateurs disposent d'une ou plusieurs horloges materielles integrees, enregistrant l'heure locale. Elles sont appelees << horloges temps reel >> (RTC). L'une d'entre elles est generalement alimentee par une pile afin de rester a l'heure une fois l'ordinateur eteint. Les RTC permettent souvent d'utiliser des alarmes et d'autres interruptions. Tous les PC i386 et les systemes bases sur ACPI ont une RTC compatible avec la puce Motorola MC146818 du PC/AT d'origine. Aujourd'hui l'horloge est generalement integree au jeu de composants de la carte mere (<< south bridge >>) et utilise une pile de secours remplacable de la taille d'une piece de monnaie. Les systemes autres que les PC, comme les systemes embarques construits autour de processeurs embarquant tout le systeme, utilisent d'autres mises en oeuvre. Generalement, ils n'offrent pas les memes fonctionnalites qu'une RTC de PC/AT. RTC vs horloge systeme Les RTC ne doivent pas etre confondues avec l'horloge systeme, qui est une horloge logicielle geree par le noyau et utilisee dans gettimeofday(2) et time(2), ainsi que pour le marquage temporel des fichiers, etc. L'horloge systeme indique le nombre de secondes et microsecondes ecoulees depuis un instant de depart, defini comme depuis l'epoque POSIX : 1er janvier 1970 a 00:00:00 (UTC). (Une mise en oeuvre usuelle compte le nombre d'interruptions, une par pulsation a une frequence de 100, 250 ou 1000 Hz.) C'est-a-dire qu'elle est supposee renvoyer l'heure locale, comme le font les RTC. Une difference cle entre une RTC et l'horloge systeme est qu'une RTC fonctionne meme lorsque le systeme est dans un etat de veille d'alimentation (incluant << eteint >>) et que l'horloge systeme ne peut fonctionner. Jusqu'a son initialisation, l'horloge systeme ne peut indiquer que le temps ecoule depuis le demarrage du systeme mais pas celui depuis l'epoque POSIX. Ainsi, au demarrage et apres la sortie de veille, l'horloge systeme sera souvent reglee a l'heure locale actuelle en utilisant une RTC. Les systemes sans RTC ont besoin de regler leur horloge systeme par un autre moyen, peut-etre a travers le reseau ou en entrant les valeurs a la main. Fonctionnalites d'une RTC Les RTC peuvent etre lues et reglees avec hwclock(8), ou directement en utilisant les ioctl(2) listes ci-dessous. En plus du compte de la date et de l'heure, de nombreuses RTC peuvent aussi generer des interruptions : - a chaque mise a jour de l'horloge (c'est-a-dire une fois par seconde) ; - a des intervalles reguliers, de frequence reglable a une puissance de 2 entre 2 Hz et 8192 Hz ; - lorsque la date d'une alarme reglee auparavant est atteinte. Chacune de ces sources d'interruptions peut etre activee ou desactivee separement. Sur de nombreux systemes, l'interruption venant de l'alarme peut etre configuree comme un evenement declenchant le reveil du systeme, et ainsi sortir le systeme d'un etat de veille d'alimentation comme la veille en RAM (STR, appelee S3 dans les systemes ACPI), l'hibernation (appelee S4 dans les systemes ACPI) ou meme l'extinction (appelee S5 dans les systemes ACPI). Sur certains systemes, la pile de secours de la RTC ne peut generer d'interruptions, alors qu'une autre le peut. Le peripherique /dev/rtc (ou /dev/rtc0, /dev/rtc1, etc.) est en lecture seule et un seul acces simultane est possible. Un processus appelant read(2) ou select(2) est bloque jusqu'a la reception de l'interruption RTC suivante. Suite a l'interruption, le processus peut lire un entier long, dont l'octet de poids faible contient le type d'interruption qui vient de se produire et les 3 octets restants contiennent le nombre d'interruptions depuis le dernier appel a read(2). Interface ioctl(2) Les appels ioctl(2) suivants sont definis sur les descripteurs des fichiers associes aux peripheriques RTC : RTC_RD_TIME Renvoie l'heure de cette RTC dans la structure suivante : struct rtc_time { int tm_sec; int tm_min; int tm_hour; int tm_mday; int tm_mon; int tm_year; int tm_wday; /* non utilise */ int tm_yday; /* non utilise */ int tm_isdst; /* non utilise */ }; Les membres de cette structure ont les memes sens et les memes portees que la ceux de la structure tm decrite dans gmtime(3). Un pointeur vers cette structure est attendu en troisieme parametre pour ioctl(2). RTC_SET_TIME Regle cette horloge RTC a l'heure specifiee par la structure rtc_time vers laquelle pointe le troisieme parametre passe a ioctl(2). Pour pouvoir modifier l'heure RTC, le processus doit etre privilegie (c'est-a-dire disposer du droit CAP_SYS_TIME). RTC_ALM_READ RTC_ALM_SET Lit et regle l'heure d'alarme, pour les horloges RTC qui gerent les alarmes. L'interruption venant de l'alarme doit etre activee ou desactivee separement en utilisant respectivement les requetes RTC_AIE_ON ou RTC_AIE_OFF. Le troisieme parametre d'ioctl(2) est un pointeur vers une structure rtc_time. Seuls les champs tm_sec, tm_min, et tm_hour de cette structure sont utilises. RTC_IRQP_READ RTC_IRQP_SET Lit et regle la frequence des interruptions, pour les horloges RTC gerant les interruptions periodiques. L'interruption periodique doit etre activee ou desactivee separement en utilisant respectivement les requetes RTC_PIE_ON ou RTC_PIE_OFF. Le troisieme parametre d'ioctl(2) est un unsigned long * ou un unsigned long respectivement. La valeur represente la frequence en interruptions par seconde. Le jeu des frequences permises est l'ensemble des multiples de deux entre 2 et 8192. Seul un processus privilegie (c'est-a-dire disposant du droit CAP_SYS_RESOURCE) peut regler une frequence superieure a celle specifiee dans /proc/sys/dev/rtc/max-user-freq, par defaut 64. RTC_AIE_ON RTC_AIE_OFF Active ou desactive l'interruption venant de l'alarme, pour les RTC qui gerent les alarmes. Le troisieme parametre d'ioctl(2) est ignore. RTC_UIE_ON RTC_UIE_OFF Active ou desactive l'interruption a chaque mise a jour, pour les horloges gerant cette interruption envoyee chaque seconde. Le troisieme parametre d'ioctl(2) est ignore. RTC_PIE_ON RTC_PIE_OFF Active ou desactive l'interruption periodique, pour les RTC gerant ces interruptions periodiques. Le troisieme parametre d'ioctl(2) est ignore. Seul un processus privilegie (c'est-a-dire disposant du droit CAP_SYS_RESOURCE) peut regler une frequence superieure a celle specifiee dans /proc/sys/dev/rtc/max-user-freq. RTC_EPOCH_READ RTC_EPOCH_SET De nombreuses RTC codent l'annee dans un registre de 8 bits, interprete soit comme un nombre binaire de 8 bits, soit comme un nombre BCD. Dans les deux cas, le nombre est interprete relativement a l'epoque de cette RTC. L'epoque de la RTC est initialise a 1900 sur la plupart des systemes, sauf sur Alpha et Mips ou il peut etre initialise a 1952, 1980 ou 2000, suivant la valeur du registre RTC destine a l'annee. Avec certaines RTC, ces operations peuvent etre utilisees respectivement pour lire ou regler l'epoque de la RTC. Le troisieme parametre ioctl(2) est respectivement un unsigned long * ou un unsigned long, et la valeur renvoyee (ou assignee) est l'epoque. Pour regler l'epoque RTC, le processus doit etre privilegie (c'est-a-dire disposer de la capacite CAP_SYS_TIME). RTC_WKALM_RD RTC_WKALM_SET Certaines RTC disposent d'une interface pour les alarmes plus puissante, utilisant ces ioctl pour lire ou ecrire l'heure de l'alarme de la RTC avec cette structure : struct rtc_wkalrm { unsigned char enabled; unsigned char pending; struct rtc_time time; }; L'attribut enabled est utilise pour activer ou desactiver l'interruption venant de l'alarme, ou pour lire son etat actuel ; lorsque ces appels sont utilises, RTC_AIE_ON et RTC_AIE_OFF ne sont pas utilises. L'attribut pending est utilise par RTC_WKALM_RD pour signaler une interruption en attente (c'est en general inutile sous Linux, excepte lors du dialogue avec la RTC geree par un microcode EFI). Le champ time est autant utilise par RTC_ALM_READ et RTC_ALM_SET, excepte que les champs tm_mday, tm_mon et tm_year sont egalement valides. Un pointeur vers cette structure doit etre passe en troisieme parametre ioctl(2). FICHIERS /dev/rtc /dev/rtc0 /dev/rtc1 ... Fichiers speciaux de peripherique caractere des differentes RTC. /proc/driver/rtc Etat de la (premiere) RTC. NOTES Lorsque l'horloge du noyau est synchronisee avec une reference externe en utilisant adjtimex(2), le noyau met a jour une RTC designee toutes les 11 minutes. Pour y parvenir, le noyau doit arreter brievement les interruptions periodiques, ce qui peut affecter les programmes utilisant cette RTC. L'epoque d'une RTC n'a rien a voir avec l'epoque POSIX, utilise uniquement pour l'horloge systeme. Si l'annee relative a l'epoque de la RTC et au registre de l'annee est inferieure a 1970, on considere que l'annee est de 100 ans superieure, c.-a-d. entre 2000 et 2069. Certaines RTC gerent les caracteres generiques (<< wildcard >>) dans les champs des alarmes, destines aux scenarios comme les alarmes periodiques toutes les quinze minutes apres chaque heure, ou au premier jour de chaque mois. Une telle utilisation n'est pas portable ; un code en espace utilisateur portable n'attend qu'une seule interruption d'alarme, puis desactivera ou reinitialisera cette alarme apres l'avoir recue. Certaines RTC gerent des interruptions de periodes multiples d'une seconde plutot qu'en fractions de secondes, des alarmes multiples, la programmation de signaux de sortie d'horloge, la memoire non volatile, et d'autres possibilites materielles qui ne sont pas accessibles par cette API. VOIR AUSSI date(1), adjtimex(2), gettimeofday(2), settimeofday(2), stime(2), time(2), gmtime(3), time(7), hwclock(8) Documentation/rtc.rst in the Linux kernel source tree 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-Pierre Giraud 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.18 8 fevrier 2026 rtc(4)