ADJTIMEX(2)

NOME
adjtimex - regola l'orologio del kernel

SINTASSI
#define _BSD_SOURCE      /* Vedere feature_test_macros(7) */
#include <sys/timex.h>
int adjtimex(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 e restituisce la medesima struttura 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, in unità di 2^-16 ppm
                        (parti per milione, vedi NOTE più avanti) */
    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 (ppm, sola lettura) */
    struct timeval time;
                     /* Ora attuale (sola lettura, eccetto che per
                        ADJ_SETOFFSET); a chiamata eseguita, time.tv_usec
                        contiene 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) (in unità
                        di 2^-16 ppm--vedi NOTE, sola lettura) */
    long jitter;     /* Variazione PPS (sola lettura); nanosecondi, se il
                        flag di stato STA_NANO è impostato, altrimenti
                        microsecondi */
    int  shift;      /* Durata dell'intervallo PPS (secondi, sola lettura) */
    long stabil;     /* Stabilità PPS (2^-16 ppm--vedi NOTE, sola lettura) */
    long jitcnt;     /* Limite variazione PPS superato (sola lettura) */
    long calcnt;     /* Intervalli di calibrazione PPS (sola lettura) */
    long errcnt;     /* Errori di calibrazione PPS (sola lettura) */
    long stbcnt;     /* 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. 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.

ADJ_FREQUENCY
    Imposta lo scostamento della frequenza da buf.freq.

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 lo stato dell'orologio da buf.status.

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.29)
    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.

ADJ_MICRO (a partire da Linux 2.6.36)
    Seleziona la risoluzione in microsecondi.

ADJ_NANO (a partire da Linux 2.6.36)
    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 BIPM (http://www.bipm.org/en/bipm/tai/tai.html)

ADJ_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(): (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 correttamente prima 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
    Abilita gli aggiornamenti dell'anello ad aggancio di fase (PLL - phase-locked loop) (in lettura e scrittura) via ADJ_OFFSET.

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

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

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

STA_INS
    Inserisce secondo intercalare (lettura-scrittura).

STA_DEL
    Toglie secondo intercalare (lettura-scrittura).

STA_UNSYNC
    Orologio non sincronizzato (lettura-scrittura).

STA_FREQHOLD
    Mantieni la frequenza (lettura-scrittura).

STA_PPSSIGNAL
    Segnale PPS presente (sola lettura).

STA_PPSJITTER
    Eccessiva variazione segnale PPS (sola lettura).

STA_PPSWANDER
    Eccessiva dispersione segnale PPS (sola lettura).

STA_PPSERROR
    Errore di calibrazione segnale PPS (sola lettura).

STA_CLOCKERR
    Difetto hardware dell'orologio (sola lettura).

STA_NANO (a partire da Linux 2.6.26)
    Risoluzione (0 = microsecondi, 1 = nanosecondi; sola lettura). 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 (a partire da Linux 2.6.26)
    Sorgente dell'orologio (0 = A, 1 = B; sola lettura).

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

VALORE RESTITUITO
In caso di successo, adjtimex() restituisce lo stato dell'orologio:

TIME_OK
    Orologio sincronizzato.

TIME_INS
    Inserire secondo intercalare.

TIME_DEL
    Togliere secondo intercalare.

TIME_OOP
    Aggiunta secondo intercalare in corso.

TIME_WAIT
    Secondo intercalare aggiunto.

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

Se fallisce, adjtimex() restituisce -1 e imposta errno.

ERRORI

EFAULT
    buf non punta a una zona di memoria scrivibile.

EINVAL
    Si è tentato di impostare buf.offset a un valore esterno all'intervallo -131071 e +131071, o di impostare buf.status a un valore diverso da quelli elencati in precedenza, o di 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.

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.

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.

CONFORMITÀ
adjtimex() è specifico di Linux e non dovrebbe essere usato in programmi pensati per la portabilità. Vedere adjtime(3) per un metodo di correzione dell'orologio di sistema, maggiormente portabile, ma meno flessibile.

VEDERE ANCHE
settimeofday(2), adjtime(3), capabilities(7), time(7), adjtimex(8)

COLOPHON
Questa pagina fa parte del rilascio 4.00 del progetto Linux man-pages. Una descrizione del progetto, le istruzioni per la segnalazione degli errori, e l'ultima versione di questa pagina si trova su http://www.kernel.org/doc/man-pages/. La versione italiana fa parte del pacchetto man-pages-it v. 4.00, a cura di: ILDP "Italian Linux Documentation Project" http://www.pluto.it/ildp
Per la traduzione in italiano si può fare riferimento a http://www.pluto.it/ildp/collaborare/
Segnalare eventuali errori di traduzione a ildp@pluto.it