plucky (2) clock_adjtime.2.gz

Provided by: manpages-it-dev_4.25.1-1_all bug

NOME

       adjtimex, clock_adjtime, ntp_adjtime - regola l'orologio del kernel

LIBRERIA

       Libreria C standard (libc, -lc)

SINTASSI

       #include <sys/timex.h>

       int adjtimex(struct timex *buf);

       int clock_adjtime(clockid_t clk_id, struct timex *buf);

       int ntp_adjtime(struct timex *buf);

DESCRIZIONE

       Linux  usa l'algoritmo di correzione dell'ora di David L. Mills (vedere RFC 5905). La chiamata di sistema
       adjtimex() legge e può all'occorrenza modificare i parametri di correzione per questo algoritmo. Richiede
       un  puntatore  a  una  struttura  timex,  aggiorna  i  parametri  del  kernel in base ai valori dei campi
       (selezionati) e restituisce la medesima struttura  aggiornata  con  i  valori  correnti  del  kernel.  La
       struttura è dichiarata nel seguente modo:

           struct timex {
               int  modes;      /* Selettore modalità */
               long offset;     /* Scostamento orario; nanosecondi, se è impostato il
                                   flag STA_NANO, altrimenti
                                   microsecondi */
               long freq;       /* Scostamento frequenza; per le unità vedi NOTE) */
               long maxerror;   /* Errore massimo (microsecondi) */
               long esterror;   /* Errore stimato (microsecondi) */
               int  status;     /* Comando/stato orologio */
               long constant;   /* Costante di tempo PLL (anello ad aggancio di fase
                                   [Phase-Locked Loop])*/
               long precision;  /* Precisione orologio
                                   (microsecondi, sola lettura) */
               long tolerance;  /* Tolleranza frequenza orologio (sola lettura);
                                   vedi NOTE per le unità */
               struct timeval time;
                                /* Ora attuale (sola lettura, eccetto che per
                                   ADJ_SETOFFSET); a chiamata eseguita, time.tv_usec
                                   ccontiene nanosecondi, se il flag di stato STA_NANO
                                   è impostato, altrimenti microsecondi) */
               long tick;       /* Microsecondi tra i battiti dell'orologio */
               long ppsfreq;    /* Frequenza PPS (impulsi al secondo)
                                   (sola lettura); vedi NOTE per le unità */
               long jitter;     /* Variazione PPS (sola lettura); nanosecondi, se il
                                   flag di stato STA_NANO è impostato, altrimenti
                                   microsecondi */
               int  shift;      /* Durata dell'intervallo PPS
                                   (secondsi, sola lettura) */
               long stabil;     /* Stabilità PPS (sola lettura);
                                   vedi NOTE per le unità */
               long jitcnt;     /* Conteggio degli eventi di limite variazione PPS
                                   superato (sola lettura) */
               long calcnt;     /* Conteggio degli intervalli di calibrazione PPS
                                   (sola lettura) */
               long errcnt;     /* Conteggio degli errori di calibrazione PPS
                                   (sola lettura) */
               long stbcnt;     /* Conteggio degli eventi di limite di stabilità PPS
                                   superato (sola lettura) */
               int tai;         /* Scostamento TAI, come impostato dall'ultima
                                   operazione ADJ_TAI (secondi, sola lettura,
                                   a partire da Linux 2.6.26) */
               /* Ulteriori byte disponibili in previsione di future espansioni */
           };

       Il  campo  modes  determina  quali  eventuali  parametri  impostare. (Come descritto più avanti in questa
       pagina, le costanti usate per ntp_adjtime() sono equivalenti ma denominate in modo diverso.) Consiste  in
       una maschera bit a bit di tipo OR che imposta zero o più dei seguenti bit:

       ADJ_OFFSET
              Imposta  lo  scostamento dell'orario da buf.offset.A partire dal kernel di Linux 2.6.26, il valore
              fornito è fissato all'intervallo (-0.5s, +0.5s). Nei kernel più vecchi si ha un errore  EINVAL  se
              il valore fornito è fuori intervallo.

       ADJ_FREQUENCY
              Imposta  lo  scostamento  della  frequenza  da  buf.freq. A partire dal kernel di Linux 2.6.26, il
              valore fornito è fissato all'intervallo (-32768000, +32768000). Nei kernel più vecchi,  si  ha  un
              errore EINVAL se il valore fornito è fuori intervallo.

       ADJ_MAXERROR
              Imposta l'errore massimo di tempo da buf.maxerror.

       ADJ_ESTERROR
              Imposta l'errore stimato di tempo da buf.esterror.

       ADJ_STATUS
              Imposta  i bit di stato dell'orologio da buf.status. Una descrizione di questi bit viene fatta più
              avanti.

       ADJ_TIMECONST
              Imposta la costante di tempo PLL da buf.constant. Se il flag di stato STA_NANO (vedi  oltre)  è  a
              zero, il kernel aggiunge 4 a questo valore.

       ADJ_SETOFFSET (a partire dal kernel di Linux 2.6.39)
              Aggiunge  buf.time  al  tempo corrente. Se buf.status include il flag ADJ_NANO, buf.time.tv_usec è
              interpretato come un valore in nanosecondi; altrimenti è considerato espresso in microsecondi.

              Il valore di buf.time è la somma dei suoi due  campi,  ma  il  campo  buf.time.tv_usec  dev'essere
              sempre non negativo. L'esempio seguente mostra come normalizzare un timeval con una risoluzione di
              nanosecondi.

                  while (buf.time.tv_usec < 0) {
                      buf.time.tv_sec  -= 1;
                      buf.time.tv_usec += 1000000000;
                  }

       ADJ_MICRO (a partire dal kernel di Linux 2.6.26)
              Seleziona la risoluzione in microsecondi.

       ADJ_NANO (a partire dal kernel di Linux 2.6.26)
              Seleziona la risoluzione in nanosecondi. Dei due flag, ADJ_MICRO e  ADJ_NANO,  solo  uno  dovrebbe
              essere specificato.

       ADJ_TAI (a partire dal kernel di Linux 2.6.26)
              Imposta lo scostamento dal TAI (Tempo Atomico Internazionale) di buf.constant.

              ADJ_TAI non si dovrebbe usare insieme a ADJ_TIMECONST, poiché anche quest'ultimo utilizza anche il
              campo buf.constant.

              Per  una  spiegazione  completa  del  TAI  e  della  differenza  tra  TAI  e  UTC,   vedere   BIPMhttp://www.bipm.org/en/bipm/tai/tai.htmlADJ_TICK
              Imposta il valore del battito da buf.tick.

       In  alternativa,  modes può essere specificato come uno dei seguenti valori (maschera multibit), nel qual
       caso non si dovrebbero utilizzare altri bit in modes:

       ADJ_OFFSET_SINGLESHOT
              Il vecchio adjtime(3): (gradualmente) aggiusta l'orario secondo il valore contenuto in buf.offset,
              che specifica una regolazione in microsecondi.

       ADJ_OFFSET_SS_READ (disponibile a partire dal kernel di Linux 2.6.28)
              Restituisce (in buf.offset) la quantità di tempo ancora da regolare dopo una precedente operazione
              ADJ_OFFSET_SINGLESHOT. Questa funzionalità è stata aggiunta nel kernel di Linux 2.6.24, ma non  ha
              funzionato correttamente prima del kernel di Linux 2.6.28.

       Gli  utenti  ordinari  sono  limitati al valore 0 o ADJ_OFFSET_SS_READ per modes. Solo il superutente può
       impostare qualsiasi parametro.

       Il campo buf.status è una maschera di bit usata per impostare e/o leggere  bit  di  stato  associati  con
       l'implementazione  NTP. Alcuni bit nella maschera possono essere usati sia per leggere che per impostare,
       mentre altri sono in sola lettura.

       STA_PLL (lettura-scrittura)
              Abilita gli aggiornamenti in modalità anello agganciato  in  fase  (PLL,  phase-locked  loop)  via
              ADJ_OFFSET.

       STA_PPSFREQ (lettura-scrittura)
              Abilita la disciplina di frequenza PPS (impulsi al secondo).

       STA_PPSTIME (lettura-scrittura)
              Abilita la disciplina di tempo PPS.

       STA_FLL (lettura-scrittura)
              Seleziona la modalità di anello ad aggancio di frequenza (FLL - frequency-locked loop).

       STA_INS (lettura-scrittura)
              Inserisce  un  secondo  intercalare  dopo  l'ultimo  secondo del giorno UTC, estendendo così di un
              secondo l'ultimo minuto del giorno. L'inserimento del secondo  intercalare  avverrà  ogni  giorno,
              purché questo flag rimanga impostato.

       STA_DEL (lettura-scrittura)
              Toglie  un  secondo  intercalare  all'ultimo  secondo  del  giorno UTC. L'eliminazione del secondo
              intercalare avverrà ogni giorno, purché questo flag rimanga impostato.

       STA_UNSYNC (lettura-scrittura)
              Orologio non sincronizzato.

       STA_FREQHOLD (lettura-scrittura)
              Mantiene la frequenza. Normalmente gli aggiustamenti  fatti  tramite  ADJ_OFFSET  implicano  anche
              aggiustamenti  minori  della  frequenza.  Così una chiamata singola corregge lo scostamento orario
              corrente,  ma  applicando  tali  scostamenti  ripetutamente  nella  stessa  direzione,  i  piccoli
              aggiustamenti della frequenza si accumuleranno per correggere la distorsione.

              Questo  flag evita che venga fatto il piccolo aggiustamento della frequenza quando si effettua una
              correzione usando il valore ADJ_OFFSET.

       STA_PPSSIGNAL (sola lettura)
              Un segnale PPS (impulsi al secondo) è presente.

       STA_PPSJITTER (sola lettura)
              Eccessiva variazione segnale PPS.

       STA_PPSWANDER (sola lettura)
              Eccessiva dispersione segnale PPS.

       STA_PPSERROR (sola lettura)
              Errore di calibrazione segnale PPS.

       STA_CLOCKERR (sola lettura)
              Difetto hardware dell'orologio.

       STA_NANO (sola lettura; a partire da Linux 2.6.26)
              Risoluzione (0 = microsecondi, 1 = nanosecondi). Impostata con ADJ_NANO, annullata con ADJ_MICRO.

       STA_MODE (a partire dal kernel di Linux 2.6.26)
              Modalità (0 = Anello ad aggancio di fase , 1 = Anello ad aggancio di frequenza).

       STA_CLK (sola lettura; a partire da Linux 2.6.26)
              Sorgente dell'orologio (0 = A, 1 = B); attualmente non usata.

       I tentativi di modificare i bit di stato in sola lettura sono ignorati senza emettere messaggi.

   clock_adjtime ()
       La chiamata di sistema clock_adjtime() (aggiunta nel kernel di Linux 2.6.39) si comporta come  adjtimex()
       ma ha un ulteriore argomento clk_id per indicare lo specifico orologio sul quale agire.

   ntp_adjtime ()
       La  funzione  di  libreria  ntp_adjtime()  (descritta  in  NTP  "Kernel Application Program API", KAPI) è
       un'interfaccia più portabile per eseguire lo stesso compito di adjtimex(). A parte i  punti  seguenti,  è
       identica a adjtimex():

       •  Le  costanti  usate  in modes hanno il prefisso "MOD_" al posto di "ADJ_", e hanno gli stessi suffissi
          (quindi, MOD_OFFSET, MOD_FREQUENCY, e così via), oltre alle eccezioni di cui ai seguenti punti.

       •  MOD_CLKA è il sinonimo di ADJ_OFFSET_SINGLESHOT.

       •  MOD_CLKB è il sinonimo di ADJ_TICK.

       •  Non ci sono sinonimi per ADJ_OFFSET_SS_READ, che non è descritto nel KAPI.

VALORE RESTITUITO

       In caso di successo, adjtimex() e ntp_adjtime() restituiscono  lo  stato  dell'orologio;  cioè,  uno  dei
       seguenti valori:

       TIME_OK     Orologio sincronizzato, nessun aggiustamento in sospeso per il secondo intercalare.

       TIME_INS    Indica che verrà aggiunto un secondo intercalare alla fine del giorno UTC.

       TIME_DEL    Indica che verrà tolto un secondo intercalare alla fine del giorno UTC.

       TIME_OOP    Aggiunta di un secondo intercalare in corso.

       TIME_WAIT   L'aggiunta  o  la  cancellazione  di un secondo intercalare è stata completata. Questo valore
                   sarà restituito prima che la successiva  operazione  ADJ_STATUS  annulli  i  flag  STA_INS  e
                   STA_DEL.

       TIME_ERROR  L'orologio  di  sistema  non  è  sincronizzato  con un server affidabile. Questo valore viene
                   restituito quando uno dei seguenti è vero:

                   •  STA_UNSYNC o STA_CLOCKERR è impostato.

                   •  STA_PPSSIGNAL è a zero e o STA_PPSFREQ o STA_PPSTIME è impostato.

                   •  STA_PPSTIME e STA_PPSJITTER sono entrambi impostati.

                   •  STA_PPSFREQ è impostato e o STA_PPSWANDER o STA_PPSJITTER è impostato.

                   Il nome simbolico TIME_BAD è un sinonimo di TIME_ERROR, fornito per retrocompatibilità.

       Si noti che a partire dal kernel di Linux 3.4, la chiamata opera in modo asincrono e il valore restituito
       usualmente non riflette un cambiamento di stato causato dalla chiamata stessa.

       Se falliscono, queste chiamate restituiscono -1 e impostano errno per indicare l'errore.

ERRORI

       EFAULT buf non punta a una zona di memoria scrivibile.

       EINVAL (kernel di Linux precedente a 2.6.26)
              È  stato  fatto  un  tentativo  per  impostare  buf.freq  a  un valore al di fuori dell'intervallo
              (-33554432, +33554432).

       EINVAL (kernel di Linux precedente a 2.6.26)
              È stato fatto un tentativo per impostare buf.offset ad  un  valore  al  di  fuori  dell'intervallo
              consentito.  Nei kernel precedenti a Linux 2.0 gli intervalli consentiti erano (-131072, +131072).
              Da Linux 2.0 in poi, gli intervalli consentiti erano (-512000, +512000).

       EINVAL È stato fatto un tentativo per impostare buf.status a un valore  diverso  da  quelli  elencati  in
              precedenza.

       EINVAL L'argomento  clk_id  dato a clock_adjtime() non è valido per una o due ragioni. Il valore di clock
              ID positivo in stile System-V  prefissato  è  fuori  intervallo,  o  il  clk_id  dinamico  non  fa
              riferimento  a  un'istanza  valida di un oggetto orologio (clock object). Si veda clock_gettime(2)
              per una spiegazione degli orologi dinamici.

       EINVAL È stato fatto un tentativo per impostare buf.tick a un valore esterno all'intervallo da  900000/HZ
              a 1100000/ HZ, dove HZ è la frequenza dell'interruzione del timer di sistema.

       ENODEV Il  dispositivo collegabile "al volo" (come per esempio USB) rappresentato da un clk_id dinamico è
              scomparso dopo che il suo dispositivo a caratteri è stato aperto. Si veda clock_gettime(2) per una
              spiegazione degli orologi dinamici.

       EOPNOTSUPP
              Il clk_id dato non supporta regolazioni.

       EPERM  buf.modes non è né a zero né a ADJ_OFFSET_SS_READ, e il chiamante non ha privilegi sufficienti. In
              Linux è richiesta l'abilitazione a CAP_SYS_TIME.

ATTRIBUTI

       Per la spiegazione dei termini usati in questa sezione, vedere attributes(7).

       ┌──────────────────────────────────────────────────────────────────────────────┬───────────────┬─────────┐
       │InterfacciaAttributoValore  │
       ├──────────────────────────────────────────────────────────────────────────────┼───────────────┼─────────┤
       │ntp_adjtime()                                                                 │ Thread safety │ MT-Safe │
       └──────────────────────────────────────────────────────────────────────────────┴───────────────┴─────────┘

CONFORME A

       adjtimex()
       clock_adjtime()
              Linux.

       L'API da preferire per il demone NTP è ntp_adjtime(3).

NOTE

       In struct timex, freq, ppsfreq e stabil sono espressi in ppm (parti per milione) con una parte frazionale
       di  16-bit,  il che significa che il valore 1 in uno di quei campi sta a indicare un valore di 2^-16 ppm,
       mentre 2^16=65536 significa 1 ppm. Questo vale sia per i valori in input  (nel  caso  di  freq)  sia  per
       quelli di output.

       L'elaborazione  del secondo intercalare innescato da STA_INS e STA_DEL è fatto dal kernel nell'ambito del
       timer. Quindi, è allo scoccare esatto di un secondo che il secondo intercalare sarà aggiunto o tolto.

VEDERE ANCHE

       clock_gettime(2),  clock_settime(2),  settimeofday(2),   adjtime(3),   ntp_gettime(3),   capabilities(7),
       time(7), adjtimex(8), hwclock(8)

       NTP "Kernel Application Program Interface" ⟨http://www.slac.stanford.edu/comp/unix/package/rtems/src/
       ssrlApps/ntpNanoclock/api.htm⟩

TRADUZIONE

       La traduzione italiana di questa pagina di manuale è stata creata da Davide Cendron
       <davcen@interfree.it>, Antonio Giovanni Colombo <azc100@gmail.com>, Marco Curreli
       <marcocurreli@tiscali.it> e Giuseppe Sacco <eppesuig@debian.org>

       Questa traduzione è documentazione libera; leggere la GNU General Public License Versione 3
       ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ o successiva per le condizioni di copyright.  Non ci
       assumiamo alcuna responsabilità.

       Per segnalare errori nella traduzione di questa pagina di manuale inviare un messaggio a ⟨pluto-
       ildp@lists.pluto.it⟩.