+\itindbeg{calendar~time}
+
+Tradizionalmente nei sistemi unix-like sono sempre stati previsti due tipi
+distinti di tempi, caratterizzati da altrettante modalità di misura ed
+espressi con diversi tipi di dati, chiamati rispettivamente \textit{calendar
+ time} e \textit{process time}, secondo le seguenti definizioni:
+\begin{basedescript}{\desclabelwidth{1.5cm}\desclabelstyle{\nextlinelabel}}
+
+\item[\textit{calendar time}] detto anche \textsl{tempo di calendario},
+ \textsl{tempo d'orologio} o \textit{tempo reale}. Si tratta di un
+ tempo assoluto o di un intervallo di tempo come lo intende
+ normalmente per le misure fatte con un orologio. Per esprimere
+ questo tempo è stato riservato il tipo \type{time\_t}, e viene
+ tradizionalmente misurato in secondi a partire dalla mezzanotte del
+ primo gennaio 1970, data che viene chiamata \textit{the Epoch}.
+
+\item[\textit{process time}] \itindex{process~time} detto anche \textsl{tempo
+ di processore} o \textsl{tempo di CPU}. Si tratta del tempo impiegato da
+ un processore nell'esecuzione del codice di un programma all'interno di un
+ processo. Per esprimere questo tempo è stato riservato il tipo
+ \type{clock\_t}, e viene misurato nei cosiddetti \itindex{clock~tick}
+ \textit{clock tick}, tradizionalmente corrispondenti al numero di
+ interruzioni del processore da parte del timer di sistema. A differenza del
+ precedente indica soltanto un intervallo di durata.
+\end{basedescript}
+
+Il \textit{calendar time} viene sempre mantenuto facendo riferimento
+al cosiddetto \textit{tempo universale coordinato} UTC, anche se
+talvolta viene usato il cosiddetto GMT (\textit{Greenwich Mean Time})
+dato che l'UTC corrisponde all'ora locale di Greenwich. Si tratta del
+tempo su cui viene mantenuto il cosiddetto \textsl{orologio di
+ sistema}, e viene usato per indicare i tempi dei file (quelli di
+sez.~\ref{sec:file_file_times}) o le date di avvio dei processi, ed è
+il tempo che viene usato dai demoni che compiono lavori amministrativi
+ad orari definito, come \cmd{cron}.
+
+Si tenga presente che questo tempo è mantenuto dal kernel e non è detto che
+corrisponda al tempo misurato dall'orologio hardware presente su praticamente
+tutte le piastre madri dei computer moderni (il cosiddetto \textit{hardware
+ clock}), il cui valore viene gestito direttamente dall'hardware in maniera
+indipendente e viene usato dal kernel soltanto all'avvio per impostare un
+valore iniziale dell'orologio di sistema. La risoluzione tradizionale data dal
+tipo di dato \type{time\_t} è di un secondo, ma nei sistemi più recenti sono
+disponibili altri tipi di dati con precisioni maggiori.
+
+Si tenga presente inoltre che a differenza di quanto avviene con altri sistemi
+operativi,\footnote{è possibile, ancorché assolutamente sconsigliabile,
+ forzare l'orologio di sistema all'ora locale per compatibilità con quei
+ sistemi operativi che han fatto questa deprecabile scelta.} l'orologio di
+sistema viene mantenuto sempre in UTC e che la conversione all'ora locale del
+proprio fuso orario viene effettuata dalle funzioni di libreria utilizzando le
+opportune informazioni di localizzazione (specificate in
+\conffile{/etc/timezone}). In questo modo si ha l'assicurazione che l'orologio
+di sistema misuri sempre un tempo monotono crescente come nella realtà, anche
+in presenza di cambi di fusi orari.
+
+\itindend{calendar~time}
+
+Il \itindex{process~time} \textit{process time} invece indica sempre una
+misura di un lasso di tempo e viene usato per tenere conto dei tempi di
+esecuzione dei processi. Esso viene sempre diviso in \textit{user time} e
+\textit{system time}, per misurare la durata di ciascun processo il kernel
+infatti calcola tre tempi:
+\begin{basedescript}{\desclabelwidth{2.2cm}\desclabelstyle{\nextlinelabel}}
+\item[\textit{clock time}] il tempo \textsl{reale}, viene chiamato anche
+ \textit{wall clock time} o \textit{elapsed time}, passato dall'avvio del
+ processo. Questo tempo fa riferimento al
+ \textit{calendar time} e dice la durata effettiva dell'esecuzione del
+ processo, ma chiaramente dipende dal carico del sistema e da quanti altri
+ processi stanno girando nello stesso momento.
+
+\item[\textit{user time}] il tempo effettivo che il processore ha impiegato
+ nell'esecuzione delle istruzioni del programma in \textit{user space}. È
+ anche quello riportato nella risorsa \var{ru\_utime} di \struct{rusage}
+ vista in sez.~\ref{sec:sys_resource_use}.
+
+\item[\textit{system time}] il tempo effettivo che il processore ha impiegato
+ per eseguire codice delle \textit{system call} nel kernel per conto del
+ processo. È anche quello riportato nella risorsa \var{ru\_stime} di
+ \struct{rusage} vista in sez.~\ref{sec:sys_resource_use}.
+\end{basedescript}
+
+La somma di \textit{user time} e \textit{system time} indica il
+\itindex{process~time} \textit{process time}, vale a dire il tempo di
+processore totale che il sistema ha effettivamente utilizzato per eseguire il
+programma di un certo processo. Si può ottenere un riassunto dei valori di
+questi tempi quando si esegue un qualsiasi programma lanciando quest'ultimo
+come argomento del comando \cmd{time}.
+
+Come accennato il \itindex{process~time} \textit{process time} viene misurato
+nei cosiddetti \itindex{clock~tick} \textit{clock tick}. Un tempo questo
+corrispondeva al numero di interruzioni effettuate dal timer di sistema, oggi
+lo standard POSIX richiede che esso sia espresso come multiplo della costante
+\const{CLOCKS\_PER\_SEC} che deve essere definita come 1000000, qualunque sia
+la risoluzione reale dell'orologio di sistema e la frequenza delle
+interruzioni del timer che, come accennato in sez.~\ref{sec:proc_hierarchy} e
+come vedremo a breve, è invece data dalla costante \const{HZ}.
+
+Il tipo di dato usato per questo tempo, \type{clock\_t}, con questa
+convenzione ha una risoluzione del microsecondo. Ma non tutte le funzioni di
+sistema come vedremo seguono questa convenzione, in tal caso il numero di
+\itindex{clock~tick} \textit{clock tick} al secondo può essere ricavato anche
+attraverso \func{sysconf} richiedendo il valore della costante
+\const{\_SC\_CLK\_TCK} (vedi sez.~\ref{sec:sys_limits}). Il vecchio simbolo
+\const{CLK\_TCK} definito in \headfile{time.h} è ormai considerato obsoleto e
+non deve essere usato.
+
+In realtà tutti calcoli dei tempi vengono effettuati dal kernel per il
+cosiddetto \textit{software clock}, utilizzando il \textit{timer di sistema} e
+facendo i conti in base al numero delle interruzioni generate dello stesso, i
+cosiddetti \itindex{jiffies} ``\textit{jiffies}''. La durata di un
+``\textit{jiffy}'' è determinata dalla frequenza di interruzione del timer,
+indicata in Hertz, come accennato in sez.~\ref{sec:proc_hierarchy}, dal valore
+della costante \const{HZ} del kernel, definita in \file{asm/param.h}.
+
+Fino al kernel 2.4 il valore di \const{HZ} era 100 su tutte le architetture
+tranne l'alpha, per cui era 1000. Con il 2.6.0 è stato portato a 1000 su tutte
+le architetture, ma dal 2.6.13 il valore è diventato una opzione di
+compilazione del kernel, con un default di 250 e valori possibili di 100, 250,
+1000. Dal 2.6.20 è stato aggiunto anche il valore 300 che è divisibile per le
+frequenze di refresh della televisione (50 o 60 Hz). Si può pensare che questi
+valori determinino anche la corrispondente durata dei \itindex{clock~tick}
+\textit{clock tick}, ma in realtà questa granularità viene calcolata in
+maniera indipendente usando la costante del kernel \const{USER\_HZ}.
+
+Fino al kernel 2.6.21 la durata di un \textit{jiffy} costituiva la risoluzione
+massima ottenibile nella misura dei tempi impiegabile in una \textit{system
+ call} (ad esempio per i timeout). Con il 2.6.21 e l'introduzione degli
+\itindex{High~Resolution~Timer~(HRT)} \textit{high-resolution timers} (HRT) è
+divenuto possibile ottenere, per le funzioni di attesa ed i timer, la massima
+risoluzione possibile fornita dall'hardware. Torneremo su questo in
+sez.~\ref{sec:sig_timer_adv}.
+
+
+
+\subsection{La gestione del \textit{process time}}
+\label{sec:sys_cpu_times}
+
+\itindbeg{process~time}
+
+Di norma tutte le operazioni del sistema fanno sempre riferimento al
+\textit{calendar time}, l'uso del \textit{process time} è riservato a
+quei casi in cui serve conoscere i tempi di esecuzione di un processo
+(ad esempio per valutarne l'efficienza). In tal caso infatti fare
+ricorso al \textit{calendar time} è inutile in quanto il tempo può
+essere trascorso mentre un altro processo era in esecuzione o in
+attesa del risultato di una operazione di I/O.
+
+La funzione più semplice per leggere il \textit{process time} di un processo è
+\funcd{clock}, che da una valutazione approssimativa del tempo di CPU
+utilizzato dallo stesso; il suo prototipo è:
+
+\begin{funcproto}{
+\fhead{time.h}
+\fdecl{clock\_t clock(void)}
+\fdesc{Legge il valore corrente del tempo di CPU.}
+}
+
+{La funzione ritorna il tempo di CPU in caso di successo e $-1$ se questo non
+ è ottenibile o rappresentabile in un valore di tipo \type{clock\_t},
+ \var{errno} non viene usata.}
+\end{funcproto}
+
+La funzione restituisce il tempo in \itindex{clock~tick} \textit{clock tick}
+ma la \acr{glibc} segue lo standard POSIX e quindi se si vuole il tempo in
+secondi occorre dividere il risultato per la costante
+\const{CLOCKS\_PER\_SEC}. In genere \type{clock\_t} viene rappresentato come
+intero a 32 bit, il che comporta un valore massimo corrispondente a circa 72
+minuti, dopo i quali il contatore riprenderà lo stesso valore iniziale.
+
+La funzione è presente anche nello standard ANSI C, ma in tal caso non è
+previsto che il valore ritornato indichi un intervallo di tempo ma solo un
+valore assoluto, per questo se si vuole la massima portabilità anche al di
+fuori di kernel unix-like, può essere opportuno chiamare la funzione
+all'inizio del programma ed ottenere il valore del tempo con una differenza.
+
+Si tenga presente inoltre che con altri kernel unix-like il valore riportato
+dalla funzione può includere anche il tempo di processore usato dai processi
+figli di cui si è ricevuto lo stato di terminazione con \func{wait} e
+affini. Questo non vale per Linux, in cui questa informazione deve essere
+ottenuta separatamente.
+
+Come accennato in sez.~\ref{sec:sys_unix_time} il tempo di processore è la
+somma di altri due tempi, l'\textit{user time} ed il \textit{system time}, che
+sono quelli effettivamente mantenuti dal kernel per ciascun processo. Questi
+possono essere letti separatamente attraverso la funzione \funcd{times}, il
+cui prototipo è:
+
+\begin{funcproto}{
+\fhead{sys/times.h}
+\fdecl{clock\_t times(struct tms *buf)}
+\fdesc{Legge il valore corrente dei tempi di processore.}
+}
+
+{La funzione ritorna un numero di \textit{clock tick} in caso di successo e
+ $-1$ per un errore, nel qual caso \var{errno} potrà assumere solo il valore
+ \errval{EFAULT} nel suo significato generico.}
+\end{funcproto}
+
+La funzione restituisce i valori di \textit{process time} del processo
+corrente in una struttura di tipo \struct{tms}, la cui definizione è riportata
+in fig.~\ref{fig:sys_tms_struct}. La struttura prevede quattro campi; i primi
+due, \var{tms\_utime} e \var{tms\_stime}, sono l'\textit{user time} ed il
+\textit{system time} del processo, così come definiti in
+sez.~\ref{sec:sys_unix_time}. Gli altri due campi, \var{tms\_cutime} e
+\var{tms\_cstime}, riportano la somma dell'\textit{user time} e del
+\textit{system time} di tutti processi figli di cui si è ricevuto lo stato di
+terminazione.
+
+\begin{figure}[!htb]
+ \footnotesize
+ \centering
+ \begin{minipage}[c]{0.8\textwidth}
+ \includestruct{listati/tms.h}
+ \end{minipage}
+ \normalsize
+ \caption{La struttura \structd{tms} dei tempi di processore associati a un
+ processo.}
+ \label{fig:sys_tms_struct}
+\end{figure}
+
+
+Si tenga presente che i tempi di processore dei processi figli di un processo
+vengono sempre sommati al valore corrente ogni volta che se ne riceve lo stato
+di terminazione, e detto valore è quello che viene a sua volta ottenuto dal
+processo padre. Pertanto nei campi \var{tms\_cutime} e \var{tms\_cstime} si
+sommano anche i tempi di ulteriori discendenti di cui i rispettivi genitori
+abbiano ricevuto lo stato di terminazione.
+
+Si tenga conto che l'aggiornamento di \var{tms\_cutime} e \var{tms\_cstime}
+viene eseguito solo quando una chiamata a \func{wait} o \func{waitpid} è
+ritornata. Per questo motivo se un processo figlio termina prima di ricevere
+lo stato di terminazione di tutti i suoi figli, questi processi
+``\textsl{nipoti}'' non verranno considerati nel calcolo di questi tempi e
+così via per i relativi ``\textsl{discendenti}''.
+
+Come accennato in sez.~\ref{sec:sys_resource_use} per i kernel precedenti la
+versione 2.6.9 il tempo di processore dei processi figli veniva sommato
+comunque chiedendo di ignorare \const{SIGCHLD} anche se lo standard POSIX
+richiede esplicitamente che questo avvenga solo quando si riceve lo stato di
+uscita con una funzione della famiglia delle \func{wait}, anche in questo caso
+il comportamento è stato adeguato allo standard a partire dalla versione
+2.6.9.
+
+A differenza di quanto avviene per \func{clock} i valori restituiti nei campi
+di una struttura \struct{tms} sono misurati in numero di \itindex{clock~tick}
+\textit{clock tick} effettivi e non in multipli di \const{CLOCKS\_PER\_SEC},
+pertanto per ottenere il valore effettivo in secondi occorrerà dividere per il
+risultato di \code{sysconf(\_SC\_CLK\_TCK)}.
+
+Lo stesso vale per il valore di ritorno della funzione, il cui significato fa
+riferimento ad un tempo relativo ad un certo punto nel passato la cui
+definizione dipende dalle diverse implementazioni, e varia anche fra diverse
+versioni del kernel. Fino al kernel 2.4 si faceva infatti riferimento al
+momento dell'avvio del kernel. Con il kernel 2.6 si fa riferimento a
+$2^{32}/\mathtt{HZ}-300$ secondi prima dell'avvio.
+
+Considerato che il numero dei \itindex{clock~tick} \textit{clock tick} per un
+kernel che è attivo da molto tempo può eccedere le dimensioni per il tipo
+\type{clock\_t} il comportamento più opportuno per i programmi è di ignorare
+comunque il valore di ritorno della funzione e ricorrere alle funzioni per il
+tempo di calendario del prossimo paragrafo qualora si voglia calcolare il
+tempo effettivamente trascorso dall'inizio del programma.
+
+Infine si tenga presente che per dei limiti nelle convenzioni per il ritorno
+dei valori delle \textit{system call} su alcune architetture hardware (ed in
+particolare la \texttt{i386} dei PC a 32 bit) nel kernel della serie 2.6 il
+valore di ritorno della funzione può risultare erroneamente uguale a $-1$,
+indicando un errore, nei primi secondi dopo il boot (per la precisione nei
+primi 41 secondi) e se il valore del contatore eccede le dimensione del tipo
+\type{clock\_t}.
+
+\itindend{process~time}
+
+
+\subsection{Le funzioni per il \textit{calendar time}}
+\label{sec:sys_time_base}
+
+\itindbeg{calendar~time}
+
+Come anticipato in sez.~\ref{sec:sys_unix_time} il \textit{calendar time}
+viene espresso normalmente con una variabile di tipo \type{time\_t}, che
+usualmente corrisponde ad un tipo elementare; in Linux è definito come
+\ctyp{long int}, che di norma corrisponde a 32 bit. Il valore corrente del
+\textit{calendar time}, che indicheremo come \textsl{tempo di sistema}, può
+essere ottenuto con la funzione \funcd{time} che lo restituisce nel suddetto
+formato, il suo prototipo è:
+
+\begin{funcproto}{
+\fhead{time.h}
+\fdecl{time\_t time(time\_t *t)}
+\fdesc{Legge il valore corrente del \textit{calendar time}.}
+}
+
+{La funzione ritorna il valore del \textit{calendar time} in caso di successo
+ e $-1$ per un errore, nel qual caso \var{errno} potrà assumere solo il
+ valore \errval{EFAULT} nel suo significato generico.}
+\end{funcproto}
+
+L'argomento \param{t}, se non nullo, deve essere l'indirizzo di una variabile
+su cui duplicare il valore di ritorno.
+
+Analoga a \func{time} è la funzione \funcd{stime} che serve per effettuare
+l'operazione inversa, e cioè per impostare il tempo di sistema qualora questo
+sia necessario; il suo prototipo è:
+
+\begin{funcproto}{
+\fhead{time.h}
+\fdecl{int stime(time\_t *t)}
+\fdesc{Imposta il valore corrente del \textit{calendar time}.}
+}
+
+{La funzione ritorna $0$ in caso di successo e $-1$ per un errore, nel qual
+ caso \var{errno} assumerà uno dei valori:
+ \begin{errlist}
+ \item[\errcode{EPERM}] non si hanno i permessi di amministrazione.
+ \end{errlist}
+ ed inoltre \errval{EFAULT} nel suo significato generico.}
+\end{funcproto}
+
+
+Dato che modificare l'ora ha un impatto su tutto il sistema il cambiamento
+dell'orologio è una operazione privilegiata e questa funzione può essere usata
+solo da un processo con i privilegi di amministratore (per la precisione la
+\textit{capability} \const{CAP\_SYS\_TIME}), altrimenti la chiamata fallirà
+con un errore di \errcode{EPERM}.
+
+Data la scarsa precisione nell'uso di \type{time\_t}, che ha una risoluzione
+massima di un secondo, quando si devono effettuare operazioni sui tempi di
+norma l'uso delle due funzioni precedenti è sconsigliato, ed esse sono di
+solito sostituite da \funcd{gettimeofday} e \funcd{settimeofday},\footnote{le
+ due funzioni \func{time} e \func{stime} sono più antiche e derivano da SVr4,
+ \func{gettimeofday} e \func{settimeofday} sono state introdotte da BSD, ed
+ in BSD4.3 sono indicate come sostitute delle precedenti, \func{gettimeofday}
+ viene descritta anche in POSIX.1-2001.} i cui prototipi sono:
+
+\begin{funcproto}{
+\fhead{sys/time.h}
+\fhead{time.h}
+\fdecl{int gettimeofday(struct timeval *tv, struct timezone *tz)}
+\fdesc{Legge il tempo corrente del sistema.}
+\fdecl{int settimeofday(const struct timeval *tv, const struct timezone *tz)}
+\fdesc{Imposta il tempo di sistema.}
+}
+
+{La funzioni ritornano $0$ in caso di successo e $-1$ per un errore, nel qual
+ caso \var{errno} assumerà i valori \errval{EINVAL}, \errval{EFAULT} e per
+ \func{settimeofday} anche \errval{EPERM}, nel loro significato generico.}
+\end{funcproto}
+
+
+Si noti come queste funzioni utilizzino per indicare il tempo una struttura di
+tipo \struct{timeval}, la cui definizione si è già vista in
+fig.~\ref{fig:sys_timeval_struct}, questa infatti permette una espressione
+alternativa dei valori del \textit{calendar time}, con una precisione,
+rispetto a \type{time\_t}, fino al microsecondo, ma la precisione è solo
+teorica, e la precisione reale della misura del tempo dell'orologio di sistema
+non dipende dall'uso di queste strutture.
+
+Come nel caso di \func{stime} anche \func{settimeofday} può essere utilizzata
+solo da un processo coi privilegi di amministratore e più precisamente con la
+capacità \const{CAP\_SYS\_TIME}. Si tratta comunque di una condizione generale
+che continua a valere per qualunque funzione che vada a modificare l'orologio
+di sistema, comprese tutte quelle che tratteremo in seguito.
+
+Il secondo argomento di entrambe le funzioni è una struttura
+\struct{timezone}, che storicamente veniva utilizzata per specificare appunto
+la \itindex{timezone} \textit{timezone}, cioè l'insieme del fuso orario e
+delle convenzioni per l'ora legale che permettevano il passaggio dal tempo
+universale all'ora locale. Questo argomento oggi è obsoleto ed in Linux non è
+mai stato utilizzato; esso non è supportato né dalle vecchie \textsl{libc5},
+né dalle \textsl{glibc}: pertanto quando si chiama questa funzione deve essere
+sempre impostato a \val{NULL}.
+
+Modificare l'orologio di sistema con queste funzioni è comunque problematico,
+in quanto esse effettuano un cambiamento immediato. Questo può creare dei
+buchi o delle ripetizioni nello scorrere dell'orologio di sistema, con
+conseguenze indesiderate. Ad esempio se si porta avanti l'orologio si possono
+perdere delle esecuzioni di \cmd{cron} programmate nell'intervallo che si è
+saltato. Oppure se si porta indietro l'orologio si possono eseguire due volte
+delle operazioni previste nell'intervallo di tempo che viene ripetuto.
+
+Per questo motivo la modalità più corretta per impostare l'ora è quella di
+usare la funzione \funcd{adjtime}, il cui prototipo è:
+
+\begin{funcproto}{
+\fhead{sys/time.h}
+\fdecl{int adjtime(const struct timeval *delta, struct timeval *olddelta)}
+\fdesc{Aggiusta l'orologio di sistema.}
+}
+
+{La funzione ritorna $0$ in caso di successo e $-1$ per un errore, nel qual
+ caso \var{errno} assumerà uno dei valori:
+ \begin{errlist}
+ \item[\errcode{EINVAL}] il valore di \param{delta} eccede il massimo
+ consentito.
+ \item[\errcode{EPERM}] il processo non i privilegi di amministratore.
+ \end{errlist}
+}
+\end{funcproto}
+
+
+Questa funzione permette di avere un aggiustamento graduale del tempo di
+sistema in modo che esso sia sempre crescente in maniera monotona. Il valore
+indicato nella struttura \struct{timeval} puntata da \param{delta} esprime il
+valore di cui si vuole spostare l'orologio. Se è positivo l'orologio sarà
+accelerato per un certo tempo in modo da guadagnare il tempo richiesto,
+altrimenti sarà rallentato.
+
+La funzione è intesa per piccoli spostamenti del tempo di sistema, ed esistono
+pertanto dei limiti massimi per i valori che si possono specificare
+per \param{delta}. La \acr{glibc} impone un intervallo compreso fra
+\code{INT\_MIN/1000000 + 2} e \code{INT\_MAX/1000000 - 2}, corrispondente, su
+una architettura PC ordinaria a 32 bit, ad un valore compreso fra $-2145$ e
+$2145$ secondi.
+
+Inoltre se si invoca la funzione prima che una precedente richiesta di
+aggiustamento sia stata completata, specificando un altro valore, il
+precedente aggiustamento viene interrotto, ma la parte dello stesso che è già
+stata completata non viene rimossa. Però è possibile in questo caso farsi
+restituire nella struttura puntata da \param{olddelta} il tempo restante della
+precedente richiesta. Fino al kernel 2.6.26 ed alla \acr{glibc} 2.8 questo
+però era possibile soltanto specificando un diverso aggiustamento
+per \param{delta}, il bug è stato corretto a partire dalle versioni citate e
+si può ottenere l'informazione relativa alla frazione di aggiustamento
+mancante usando il valore \val{NULL} per \param{delta}.
+
+Linux poi prevede una specifica funzione di sistema che consente un
+aggiustamento molto più dettagliato del tempo, permettendo ad esempio anche di
+regolare anche la velocità e le derive dell'orologio di sistema. La funzione
+è \funcd{adjtimex} ed il suo prototipo è:
+
+\begin{funcproto}{
+\fhead{sys/timex.h}
+\fdecl{int adjtimex(struct timex *buf)}
+\fdesc{Regola l'orologio di sistema.}
+}
+
+{La funzione ritorna lo stato dell'orologio (un valore $\ge 0$) in caso di
+ successo e $-1$ per un errore, nel qual caso \var{errno} assumerà uno dei
+ valori:
+ \begin{errlist}
+ \item[\errcode{EINVAL}] si sono indicati valori fuori dall'intervallo
+ consentito per qualcuno dei campi di \param{buf}.
+ \item[\errcode{EPERM}] si è richiesta una modifica dei parametri ed il
+ processo non ha i privilegi di amministratore.
+ \end{errlist}
+ ed inoltre \errval{EFAULT} nel suo significato generico.}
+\end{funcproto}
+
+In caso di successo la funzione restituisce un valore numerico non negativo
+che indica lo stato dell'orologio, che può essere controllato con i valori
+delle costanti elencate in tab.~\ref{tab:adjtimex_return}.
+
+\begin{table}[!htb]
+ \footnotesize
+ \centering
+ \begin{tabular}[c]{|l|c|l|}
+ \hline
+ \textbf{Nome} & \textbf{Valore} & \textbf{Significato}\\
+ \hline
+ \hline
+ \const{TIME\_OK} & 0 & Orologio sincronizzato.\\
+ \const{TIME\_INS} & 1 & Inserimento di un \textit{leap second}.\\
+ \const{TIME\_DEL} & 2 & Cancellazione di un \textit{leap second}.\\
+ \const{TIME\_OOP} & 3 & \textit{leap second} in corso.\\
+ \const{TIME\_WAIT} & 4 & \textit{leap second} avvenuto.\\
+ \const{TIME\_BAD} & 5 & Orologio non sincronizzato.\\
+ \hline
+ \end{tabular}
+ \caption{Possibili valori ritornati da \func{adjtimex} in caso di successo.}
+ \label{tab:adjtimex_return}
+\end{table}
+
+La funzione richiede come argomento il puntatore ad una struttura di tipo
+\struct{timex}, la cui definizione, effettuata in \headfile{sys/timex.h}, è
+riportata in fig.~\ref{fig:sys_timex_struct} per i campi che interessano la
+possibilità di essere modificati documentati anche nella pagina di manuale. In
+realtà la struttura è stata estesa con ulteriori campi, i cui valori sono
+utilizzabili solo in lettura, la cui definizione si può trovare direttamente
+
+\begin{figure}[!htb]
+ \footnotesize \centering
+ \begin{minipage}[c]{\textwidth}
+ \includestruct{listati/timex.h}
+ \end{minipage}
+ \normalsize
+ \caption{La struttura \structd{timex} per il controllo dell'orologio di
+ sistema.}
+ \label{fig:sys_timex_struct}
+\end{figure}
+
+L'azione della funzione dipende dal valore del campo \var{mode}
+di \param{buf}, che specifica quale parametro dell'orologio di sistema,
+specificato nel corrispondente campo di \struct{timex}, deve essere
+impostato. Un valore nullo serve per leggere i parametri correnti, i valori
+diversi da zero devono essere specificati come OR binario delle costanti
+riportate in tab.~\ref{tab:sys_timex_mode}.
+
+\begin{table}[!htb]
+ \footnotesize
+ \centering
+ \begin{tabular}[c]{|l|c|p{8cm}|}
+ \hline
+ \textbf{Nome} & \textbf{Valore} & \textbf{Significato}\\
+ \hline
+ \hline
+ \const{ADJ\_OFFSET} & 0x0001 & Imposta la differenza fra il tempo
+ reale e l'orologio di sistema:
+ deve essere indicata in microsecondi
+ nel campo \var{offset} di
+ \struct{timex}.\\
+ \const{ADJ\_FREQUENCY} & 0x0002 & Imposta la differenza in frequenza
+ fra il tempo reale e l'orologio di
+ sistema: deve essere indicata
+ in parti per milione nel campo
+ \var{frequency} di \struct{timex}.\\
+ \const{ADJ\_MAXERROR} & 0x0004 & Imposta il valore massimo
+ dell'errore sul tempo, espresso in
+ microsecondi nel campo
+ \var{maxerror} di \struct{timex}.\\
+ \const{ADJ\_ESTERROR} & 0x0008 & Imposta la stima dell'errore
+ sul tempo, espresso in microsecondi
+ nel campo \var{esterror} di
+ \struct{timex}.\\
+ \const{ADJ\_STATUS} & 0x0010 & Imposta alcuni valori di stato
+ interni usati dal
+ sistema nella gestione
+ dell'orologio specificati nel campo
+ \var{status} di \struct{timex}.\\
+ \const{ADJ\_TIMECONST} & 0x0020 & Imposta la larghezza di banda del
+ PLL implementato dal kernel,
+ specificato nel campo
+ \var{constant} di \struct{timex}.\\
+ \const{ADJ\_TICK} & 0x4000 & Imposta il valore dei \textit{tick}
+ \itindex{clock~tick} del timer in
+ microsecondi, espresso nel campo
+ \var{tick} di \struct{timex}.\\
+ \const{ADJ\_OFFSET\_SINGLESHOT}&0x8001&Chiede uno spostamento una tantum
+ dell'orologio secondo il valore del
+ campo \var{offset} simulando il
+ comportamento di \func{adjtime}.\\
+ \hline
+ \end{tabular}
+ \caption{Costanti per l'assegnazione del valore del campo \var{mode} della
+ struttura \struct{timex}.}
+ \label{tab:sys_timex_mode}
+\end{table}
+
+La funzione utilizza il meccanismo di David L. Mills, descritto
+nell'\href{http://www.ietf.org/rfc/rfc1305.txt}{RFC~1305}, che è alla base del
+protocollo NTP. La funzione è specifica di Linux e non deve essere usata se la
+portabilità è un requisito, le \acr{glibc} provvedono anche un suo omonimo
+\func{ntp\_adjtime}. La trattazione completa di questa funzione necessita di
+una lettura approfondita del meccanismo descritto nell'RFC~1305, ci limitiamo
+a descrivere in tab.~\ref{tab:sys_timex_mode} i principali valori utilizzabili
+per il campo \var{mode}, un elenco più dettagliato del significato dei vari
+campi della struttura \struct{timex} può essere ritrovato in \cite{GlibcMan}.
+
+Il valore delle costanti per \var{mode} può essere anche espresso, secondo la
+sintassi specificata per la forma equivalente di questa funzione definita come
+\func{ntp\_adjtime}, utilizzando il prefisso \code{MOD} al posto di
+\code{ADJ}.
+
+Si tenga presente infine che con l'introduzione a partire dal kernel 2.6.21
+degli \itindex{High~Resolution~Timer~(HRT)} \textit{high-resolution timer} ed
+il supporto per i cosiddetti POSIX \textit{real-time clock}, si può ottenere
+il \textit{calendar time} direttamente da questi, come vedremo in
+sez.~\ref{sec:sig_timer_adv}, con la massima risoluzione possibile per
+l'hardware della macchina.
+
+
+
+\subsection{La gestione delle date.}
+\label{sec:sys_date}
+
+\itindbeg{broken-down~time}
+
+Le funzioni viste al paragrafo precedente sono molto utili per trattare le
+operazioni elementari sui tempi, però le rappresentazioni del tempo ivi
+illustrate, se han senso per specificare un intervallo, non sono molto
+intuitive quando si deve esprimere un'ora o una data. Per questo motivo è
+stata introdotta una ulteriore rappresentazione, detta \textit{broken-down
+ time}, che permette appunto di \textsl{suddividere} il \textit{calendar
+ time} usuale in ore, minuti, secondi, ecc. e viene usata tenendo conto
+anche dell'eventuale utilizzo di un fuso orario.
+
+\begin{figure}[!htb]
+ \footnotesize \centering
+ \begin{minipage}[c]{.8\textwidth}
+ \includestruct{listati/tm.h}
+ \end{minipage}
+ \normalsize
+ \caption{La struttura \structd{tm} per una rappresentazione del tempo in
+ termini di ora, minuti, secondi, ecc.}
+ \label{fig:sys_tm_struct}
+\end{figure}