Provided by: manpages-it-dev_4.19.0-7_all bug

NOME

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

LIBRARY

       Standard C library (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. Mill (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
       seguento 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 da 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 da 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 massimmo 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 da 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  normalzzare  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 da Linux 2.6.26)
              Seleziona la risoluzione in microsecondi.

       ADJ_NANO (a partire da 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 da 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
              impiega 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 il tempo secondo il valore contenuto
              in buf.offset, che specifica una regolazione in microsecondi.

       ADJ_OFFSET_SS_READ (disponibile a partire da 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
              in Linux 2.6.24, ma non ha funzionato correttamenteprima 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 dell'anello ad aggancio di 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 aggiustamente 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 da Linux 2.6.26)
              Modalità (0 = Anello ad aggancio di fase , 1 = Anello  ad  aggancio  di  frequenza;
              sola lettura).

       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 in in Linux 2.6.39)  si  comporta  come
       adjtimex()  ma  ha  un  uteriore  argomento  clk_id per indicare lo specifico orologio sul
       quale agisce.

   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 da Linux 3.4, la chiamata  opera  in  modo  asincrono  e  il  valore
       restituito  usualmente  non  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 (before Linux 2.6.26)
              É stato fatto un  tentativo  per  impostare  buf.freq  a  un  valore  al  di  fuori
              dell'intervallo (-33554432, +33554432).

       EINVAL (before Linux 2.6.26)
              An  attempt  was  made  to  set  buf.offset to a value outside the permitted range.
              Before Linux 2.0, the permitted range  was  (-131072,  +131072).   From  Linux  2.0
              onwards, the permitted range was (-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)  rapresentato  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 │
       └───────────────────────────────────────────────────────────────┴───────────────┴─────────┘

STANDARDS

       Nessuna di queste interfacce è descritta in POSIX.1

       adjtimex()  e  clock_adjtime()   sono  specifici  di  Linux e non dovrebbe essere usato in
       programmi pensati per la portabilità.

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

NOTE

       In struct timex, freq, ppsfreq, and stabil are ppm  (parts  per  million)  with  a  16-bit
       fractional part, which means that a value of 1 in one of those fields actually means 2^-16
       ppm, and 2^16=65536 is 1 ppm.  This is the case for both input  values  (in  the  case  of
       freq)  and output values.

       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> e Marco Curreli
       <marcocurreli@tiscali.it>

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