Provided by: manpages-fr_3.23.1-1_all bug

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   oeuvre.   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  étant
       le  « POSIX  Epoch » : 1er janvier 1970 à 0h00 UTC. (Une mise en oeuvre
       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 le « POSIX Epoch ». 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 dune RTC
       Les RTC peuvent être lues et réglées avec hwclock(8), ou directement en
       utilisant les ioctl 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.-à-d.. 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é (i.e. 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é (i.e. 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é  (i.e.
              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’Epoch  de  cette  RTC.  L’Epoch 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’Epoch de la RTC. Le troisième paramètre ioctl(2) est
              respectivement  un  unsigned  long *  ou un unsigned long, et la
              valeur de retour (ou assignée) est l’Epoch. Pour régler  l’Epoch
              RTC,  le  processus doit être privilégié (i.e. disposer du droit
              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  en  mode  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’Epoch  d’une  RTC  n’a  rien  à  voir  avec  l’Epoch  POSIX,  utilisé
       uniquement pour l’horloge système.

       Si l’année relative à l’Epoch 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),
       /usr/src/linux/Documentation/rtc.txt

COLOPHON

       Cette page fait partie de  la  publication  3.23  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

       Cette  page  de  manuel  a  été  traduite et mise à jour par Christophe
       Blaess <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis  par
       Alain  Portal  <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et mise à
       disposition sur http://manpagesfr.free.fr/.

       Les mises à jour et corrections de la version présente dans Debian sont
       directement          gérées          par         Simon         Paillard
       <simon.paillard@resel.enst-bretagne.fr>  et  l’équipe  francophone   de
       traduction de Debian.

       Veuillez   signaler   toute   erreur   de   traduction  en  écrivant  à
       <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
       paquet manpages-fr.

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