Provided by: manpages-fr_4.26.0-1_all 
NOM
rtc – Horloge temps réel
SYNOPSIS
#include <linux/rtc.h>
int ioctl(fd, RTC_request, param);
DESCRIPTION
Il s'agit d'une interface aux pilotes pour les horloges temps réel (RTC).
La plupart des ordinateurs disposent d'une ou plusieurs horloges matérielles intégrées, enregistrant
l'heure locale. Elles sont appelées « horloges temps réel » (RTC). L'une d'entre elles est généralement
alimentée par une pile afin de rester à l'heure une fois l'ordinateur éteint. Les RTC permettent souvent
d'utiliser des alarmes et d'autres interruptions.
Tous les PC i386 et les systèmes basés sur ACPI ont une RTC compatible avec la puce Motorola MC146818 du
PC/AT d'origine. Aujourd'hui l'horloge est généralement intégrée au jeu de composants de la carte mère
(« south bridge ») et utilise une pile de secours remplaçable de la taille d'une pièce de monnaie.
Les systèmes autres que les PC, comme les systèmes embarqués construits autour de processeurs embarquant
tout le système, utilisent d'autres mises en œuvre. Généralement, ils n'offrent pas les mêmes
fonctionnalités qu'une RTC de PC/AT.
RTC vs horloge système
Les RTC ne doivent pas être confondues avec l'horloge système, qui est une horloge logicielle gérée par
le noyau et utilisée dans gettimeofday(2) et time(2), ainsi que pour le marquage temporel des fichiers,
etc. L'horloge système indique le nombre de secondes et microsecondes écoulées depuis un instant de
départ, défini comme depuis l'époque POSIX : 1er janvier 1970 à 00:00:00 (UTC). (Une mise en œuvre
usuelle compte le nombre d'interruptions, une par pulsation à une fréquence de 100, 250 ou 1000 Hz.)
C'est-à-dire qu'elle est supposée renvoyer l'heure locale, comme le font les RTC.
Une différence clé entre une RTC et l'horloge système est qu'une RTC fonctionne même lorsque le système
est dans un état de veille d'alimentation (incluant « éteint ») et que l'horloge système ne peut
fonctionner. Jusqu'à son initialisation, l'horloge système ne peut indiquer que le temps écoulé depuis le
démarrage du système mais pas celui depuis l'époque POSIX. Ainsi, au démarrage et après la sortie de
veille, l'horloge système sera souvent réglée à l'heure locale actuelle en utilisant une RTC. Les
systèmes sans RTC ont besoin de régler leur horloge système par un autre moyen, peut-être à travers le
réseau ou en entrant les valeurs à la main.
Fonctionnalités d'une RTC
Les RTC peuvent être lues et réglées avec hwclock(8), ou directement en utilisant les ioctl(2) listés
ci-dessous.
En plus du compte de la date et de l'heure, de nombreuses RTC peuvent aussi générer des interruptions :
- à chaque mise à jour de l'horloge (c'est-à-dire une fois par seconde) ;
- à des intervalles réguliers, de fréquence réglable à une puissance de 2 entre 2 Hz et 8192 Hz ;
- lorsque la date d'une alarme réglée auparavant est atteinte.
Chacune de ces sources d'interruptions peut être activée ou désactivée séparément. Sur de nombreux
systèmes, l'interruption venant de l'alarme peut être configurée comme un événement déclenchant le réveil
du système, et ainsi sortir le système d'un état de veille d'alimentation comme la veille en RAM (STR,
appelée S3 dans les systèmes ACPI), l'hibernation (appelée S4 dans les systèmes ACPI) ou même
l'extinction (appelée S5 dans les systèmes ACPI). Sur certains systèmes, la pile de secours de la RTC ne
peut générer d'interruptions, alors qu'une autre le peut.
Le périphérique /dev/rtc (ou /dev/rtc0, /dev/rtc1, etc.) est en lecture seule et un seul accès simultané
est possible. Un processus appelant read(2) ou select(2) est bloqué jusqu'à la réception de
l'interruption RTC suivante. Suite à 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 à read(2).
Interface ioctl(2)
Les appels ioctl(2) suivants sont définis sur les descripteurs des fichiers associés aux périphériques
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 utilisé */
int tm_yday; /* non utilisé */
int tm_isdst; /* non utilisé */
};
Les membres de cette structure ont les mêmes sens et les mêmes portées que la ceux de la structure
tm décrite dans gmtime(3). Un pointeur vers cette structure est attendu en troisième paramètre
pour ioctl(2).
RTC_SET_TIME
Règle cette horloge RTC à l'heure spécifiée par la structure rtc_time vers laquelle pointe le
troisième paramètre passé à ioctl(2). Pour pouvoir modifier l'heure RTC, le processus doit être
privilégié (c'est-à-dire disposer du droit CAP_SYS_TIME).
RTC_ALM_READ
RTC_ALM_SET
Lit et règle l'heure d'alarme, pour les horloges RTC qui gèrent les alarmes. L'interruption venant
de l'alarme doit être activée ou désactivée séparément en utilisant respectivement les requêtes
RTC_AIE_ON ou RTC_AIE_OFF. Le troisième paramètre 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 utilisés.
RTC_IRQP_READ
RTC_IRQP_SET
Lit et règle la fréquence des interruptions, pour les horloges RTC gérant les interruptions
périodiques. L'interruption périodique doit être activée ou désactivée séparément en utilisant
respectivement les requêtes RTC_PIE_ON ou RTC_PIE_OFF. Le troisième paramètre d'ioctl(2) est un
unsigned long * ou un unsigned long respectivement. La valeur représente la fréquence en
interruptions par seconde. Le jeu des fréquences permises est l'ensemble des multiples de deux
entre 2 et 8192. Seul un processus privilégié (c'est-à-dire disposant du droit CAP_SYS_RESOURCE)
peut régler une fréquence supérieure à celle spécifiée dans /proc/sys/dev/rtc/max-user-freq, par
défaut 64.
RTC_AIE_ON
RTC_AIE_OFF
Active ou désactive l'interruption venant de l'alarme, pour les RTC qui gèrent les alarmes. Le
troisième paramètre d'ioctl(2) est ignoré.
RTC_UIE_ON
RTC_UIE_OFF
Active ou désactive l'interruption à chaque mise à jour, pour les horloges gérant cette
interruption envoyée chaque seconde. Le troisième paramètre d'ioctl(2) est ignoré.
RTC_PIE_ON
RTC_PIE_OFF
Active ou désactive l'interruption périodique, pour les RTC gérant ces interruptions périodiques.
Le troisième paramètre d'ioctl(2) est ignoré. Seul un processus privilégié (c'est-à-dire disposant
du droit CAP_SYS_RESOURCE) peut régler une fréquence supérieure à celle spécifiée dans
/proc/sys/dev/rtc/max-user-freq.
RTC_EPOCH_READ
RTC_EPOCH_SET
De nombreuses RTC codent l'année dans un registre de 8 bits, interprété soit comme un nombre
binaire de 8 bits, soit comme un nombre BCD. Dans les deux cas, le nombre est interprété
relativement à l'époque de cette RTC. L'époque de la RTC est initialisé à 1900 sur la plupart des
systèmes, sauf sur Alpha et Mips où il peut être initialisé à 1952, 1980 ou 2000, suivant la
valeur du registre RTC destiné à l'année. Avec certaines RTC, ces opérations peuvent être
utilisées respectivement pour lire ou régler l'époque de la RTC. Le troisième paramètre ioctl(2)
est respectivement un unsigned long * ou un unsigned long, et la valeur renvoyée (ou assignée) est
l'époque. Pour régler l'époque RTC, le processus doit être privilégié (c'est-à-dire disposer de la
capacité 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 écrire 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 utilisé pour activer ou désactiver l'interruption venant de l'alarme, ou
pour lire son état actuel ; lorsque ces appels sont utilisés, RTC_AIE_ON et RTC_AIE_OFF ne sont
pas utilisés. L'attribut pending est utilisé par RTC_WKALM_RD pour signaler une interruption en
attente (c'est en général inutile sous Linux, excepté lors du dialogue avec la RTC gérée par un
microcode EFI). Le champ time est autant utilisé par RTC_ALM_READ et RTC_ALM_SET, excepté que les
champs tm_mday, tm_mon et tm_year sont également valides. Un pointeur vers cette structure doit
être passé en troisième paramètre ioctl(2).
FICHIERS
/dev/rtc
/dev/rtc0
/dev/rtc1
... Fichiers spéciaux de périphérique caractère des différentes RTC.
/proc/driver/rtc
État de la (première) RTC.
NOTES
Lorsque l'horloge du noyau est synchronisée avec une référence externe en utilisant adjtimex(2), le noyau
met à jour une RTC désignée toutes les 11 minutes. Pour y parvenir, le noyau doit arrêter brièvement les
interruptions périodiques, ce qui peut affecter les programmes utilisant cette RTC.
L'époque d'une RTC n'a rien à voir avec l'époque POSIX, utilisé uniquement pour l'horloge système.
Si l'année relative à l'époque de la RTC et au registre de l'année est inférieure à 1970, on considère
que l'année est de 100 ans supérieure, c.-à-d. entre 2000 et 2069.
Certaines RTC gèrent les caractères génériques (« wildcard ») dans les champs des alarmes, destinés aux
scénarios comme les alarmes périodiques toutes les quinze minutes après 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 désactivera ou réinitialisera cette alarme après
l'avoir reçue.
Certaines RTC gèrent des interruptions de périodes multiples d'une seconde plutôt qu'en fractions de
secondes, des alarmes multiples, la programmation de signaux de sortie d'horloge, la mémoire non
volatile, et d'autres possibilités matérielles 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.txt dans les sources du noyau Linux.
TRADUCTION
La traduction française de cette page de manuel a été créée par Christophe Blaess
<https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry Vignaud
<tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard
<fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau
<jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François
<nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard
<simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prévot
<david@tilapin.org> et Jean-Pierre Giraud <jean-pierregiraud@neuf.fr>
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.
Pages du manuel de Linux 6.9.1 2 mai 2024 rtc(4)