Provided by: manpages-fr_3.65d1p1-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 œ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 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'é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 de retour (ou
              assignée) est l'époque. Pour régler l'époque 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  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

COLOPHON

       Cette  page  fait partie de la publication 3.65 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).  Simon  Paillard  et  l'équipe  francophone  de
       traduction de Debian (2006-2009).

       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> ».