Provided by: manpages-it-dev_4.15.0-9_all 
NOME
adjtimex, clock_adjtime, ntp_adjtime - regola l'orologio del kernel
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 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(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 (kernel precedenti a Linux 2.6.26)
É stato fatto un tentativo per impostare buf.freq a un valore al di fuori
dell'intervallo (-33554432, +33554432).
EINVAL (kernel precedenti a Linux 2.6.26)
É stato fatto un tentativo per impostare buf.offset a 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) 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).
┌───────────────────────────────────────────────────────────────┬───────────────┬─────────┐
│Interfaccia │ Attributo │ Valore │
├───────────────────────────────────────────────────────────────┼───────────────┼─────────┤
│ntp_adjtime() │ Thread safety │ MT-Safe │
└───────────────────────────────────────────────────────────────┴───────────────┴─────────┘
CONFORME A
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 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⟩
COLOPHON
Questa pagina fa parte del rilascio 5.13 del progetto Linux man-pages. Una descrizione del
progetto, le istruzioni per la segnalazione degli errori, e l'ultima versione di questa
pagina si trovano su https://www.kernel.org/doc/man-pages/.
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⟩.