\const{STREAM\_MAX}& 8& Massimo numero di stream aperti per
processo in contemporanea.\\
\const{TZNAME\_MAX}& 6& Dimensione massima del nome di una
- \texttt{timezone} (vedi
+ \itindex{timezone} \textit{timezone} (vedi
sez.~\ref{sec:sys_time_base})).\\
\const{NGROUPS\_MAX}& 32& Numero di gruppi supplementari per
processo (vedi sez.~\ref{sec:proc_access_id}).\\
\const{\_POSIX\_STREAM\_MAX} & 8& Massimo numero di stream aperti per
processo in contemporanea.\\
\const{\_POSIX\_TZNAME\_MAX} & 6& Dimensione massima del nome di una
- \textit{timezone} (vedi
- sez.~\ref{sec:sys_date}). \\
+ \itindex{timezone} \textit{timezone}
+ (vedi sez.~\ref{sec:sys_date}). \\
\const{\_POSIX\_RTSIG\_MAX} & 8& Numero massimo di segnali
\textit{real-time} (vedi
sez.~\ref{sec:sig_real_time}).\\
che specifica la macro {FOPEN\_MAX}.\\
\texttt{\_SC\_TZNAME\_MAX}& \const{TZNAME\_MAX}&
La dimensione massima di un nome di una
- \texttt{timezone} (vedi
+ \itindex{timezone} \texttt{timezone} (vedi
sez.~\ref{sec:sys_date}).\\
\texttt{\_SC\_NGROUPS\_MAX}&\const{NGROUP\_MAX}&
Massimo numero di gruppi supplementari che
\itindbeg{calendar~time}
-Come anticipato in sez.~\ref{sec:sys_unix_time} il \textit{calendar time} è
-mantenuto dal kernel in 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 è:
+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}
\itindex{capabilities} 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 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,
+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.} i cui prototipi
-sono:
-\begin{functions}
- \headdecl{sys/time.h}
- \headdecl{time.h}
-
- \funcdecl{int gettimeofday(struct timeval *tv, struct timezone *tz)}
+ 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}
- Legge il tempo corrente del sistema.
-
- \funcdecl{int settimeofday(const struct timeval *tv, const struct timezone
- *tz)}
-
- Imposta il tempo di sistema.
-
- \bodydesc{Entrambe le funzioni restituiscono 0 in caso di successo e -1 in
- caso di errore, nel qual caso \var{errno} può assumere i valori
- \errval{EINVAL} \errval{EFAULT} e per \func{settimeofday} anche
- \errval{EPERM}.}
-\end{functions}
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.\footnote{la precisione è solo
- teorica, la precisione reale della misura del tempo dell'orologio di sistema
- non dipende dall'uso di queste strutture.}
+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} (la cosa continua a
-valere per qualunque funzione che vada a modificare l'orologio di sistema,
-quindi anche per quelle che tratteremo in seguito) può essere utilizzata solo
-da un processo coi privilegi di amministratore.\footnote{più precisamente la
- capability \const{CAP\_SYS\_TIME}.}
+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
+\itindex{capability} 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 \textit{time zone}, 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}.
+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
Per questo motivo la modalità più corretta per impostare l'ora è quella di
usare la funzione \funcd{adjtime}, il cui prototipo è:
-\begin{prototype}{sys/time.h}
-{int adjtime(const struct timeval *delta, struct timeval *olddelta)}
-
- Aggiusta del valore \param{delta} l'orologio di sistema.
-
- \bodydesc{La funzione restituisce 0 in caso di successo e -1 in caso di
- errore, nel qual caso \var{errno} assumerà il valore \errcode{EPERM}.}
-\end{prototype}
+
+\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{EPERM}] il processo non i privilegi di amministratore.
+ \item[\errcode{EINVAL}] il valore di \param{delta} eccede il massimo
+ consentito.
+ \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
-di \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. Il secondo argomento viene
-usato, se non nullo, per ricevere il valore dell'ultimo aggiustamento
-effettuato.
+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{EPERM}] si è richiesta una modifica dei parametri ed il
+ processo non ha i privilegi di amministratore.
+ \item[\errcode{EINVAL}] si sono indicati valori fuori dall'intervallo
+ consentito per qualcuno dei campi di \param{buf}.
+ \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
\label{fig:sys_timex_struct}
\end{figure}
-Linux poi prevede un'altra funzione, che consente un aggiustamento molto più
-dettagliato del tempo, permettendo ad esempio anche di modificare anche la
-velocità dell'orologio di sistema. La funzione è \funcd{adjtimex} ed il suo
-prototipo è:
-\begin{prototype}{sys/timex.h}
-{int adjtimex(struct timex *buf)}
-
- Aggiusta del valore \param{delta} l'orologio di sistema.
-
- \bodydesc{La funzione restituisce lo stato dell'orologio (un valore $>0$) in
- caso di successo e -1 in caso di errore, nel qual caso \var{errno}
- assumerà i valori \errval{EFAULT}, \errval{EINVAL} ed \errval{EPERM}.}
-\end{prototype}
-
-La funzione richiede una struttura di tipo \struct{timex}, la cui definizione,
-così come effettuata in \headfile{sys/timex.h}, è riportata in
-fig.~\ref{fig:sys_timex_struct}. L'azione della funzione dipende dal valore
-del campo \var{mode}, che specifica quale parametro dell'orologio di sistema,
-specificato in un opportuno 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}.
-
-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}.
+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{8.5cm}|}
+ \begin{tabular}[c]{|l|c|p{8cm}|}
\hline
\textbf{Nome} & \textbf{Valore} & \textbf{Significato}\\
\hline
deve essere indicata in microsecondi
nel campo \var{offset} di
\struct{timex}.\\
- \const{ADJ\_FREQUENCY} & 0x0002 & Imposta la differenze in frequenza
+ \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}.\\
+ 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
+ \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}.\\
\itindex{clock~tick} del timer in
microsecondi, espresso nel campo
\var{tick} di \struct{timex}.\\
- \const{ADJ\_OFFSET\_SINGLESHOT}&0x8001&Imposta uno spostamento una tantum
+ \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}.\\
\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}.
-\begin{table}[htb]
- \footnotesize
- \centering
- \begin{tabular}[c]{|l|c|l|}
- \hline
- \textbf{Nome} & \textbf{Valore} & \textbf{Significato}\\
- \hline
- \hline
- \const{TIME\_OK} & 0 & L'orologio è sincronizzato.\\
- \const{TIME\_INS} & 1 & Insert leap second.\\
- \const{TIME\_DEL} & 2 & Delete leap second.\\
- \const{TIME\_OOP} & 3 & Leap second in progress.\\
- \const{TIME\_WAIT} & 4 & Leap second has occurred.\\
- \const{TIME\_BAD} & 5 & L'orologio non è sincronizzato.\\
- \hline
- \end{tabular}
- \caption{Possibili valori di ritorno di \func{adjtimex}.}
- \label{tab:sys_adjtimex_return}
-\end{table}
-
-La funzione ritorna un valore positivo che esprime lo stato dell'orologio di
-sistema; questo può assumere i valori riportati in
-tab.~\ref{tab:sys_adjtimex_return}. Un valore di -1 viene usato per riportare
-un errore; al solito se si cercherà di modificare l'orologio di sistema
-(specificando un \var{mode} diverso da zero) senza avere i privilegi di
-amministratore si otterrà un errore di \errcode{EPERM}.
+Si tenga presente infine che con l'introduzione a partire dal kernel 2.6.21
+degli \itindex{high~resolution~timer} \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.
+ 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}
Questo viene effettuato attraverso una opportuna struttura \struct{tm}, la cui
definizione è riportata in fig.~\ref{fig:sys_tm_struct}, ed è in genere questa
struttura che si utilizza quando si deve specificare un tempo a partire dai
-dati naturali (ora e data), dato che essa consente anche di trattare la
-gestione del fuso orario e dell'ora legale.\footnote{in realtà i due campi
- \var{tm\_gmtoff} e \var{tm\_zone} sono estensioni previste da BSD e dalle
- \acr{glibc}, che, quando è definita \macro{\_BSD\_SOURCE}, hanno la forma in
- fig.~\ref{fig:sys_tm_struct}.}
+dati naturali (ora e data), dato che essa consente anche di tenere conto della
+gestione del fuso orario e dell'ora legale. In particolare gli ultimi due
+campi, \var{tm\_gmtoff} e \var{tm\_zone}, sono estensioni previste da BSD e
+supportate dalla \acr{glibc} quando è definita la macro \macro{\_BSD\_SOURCE}.
+
+Ciascuno dei campi di \struct{tm} ha dei precisi intervalli di valori
+possibili, con convenzioni purtroppo non troppo coerenti. Ad esempio
+\var{tm\_sec} che indica i secondi deve essere nell'intervallo da 0 a 59, ma è
+possibile avere anche il valore 60 per un cosiddetto \textit{leap second} (o
+\textsl{secondo intercalare}), cioè uno di quei secondi aggiunti al calcolo
+dell'orologio per effettuare gli aggiustamenti del calendario per tenere conto
+del disallineamento con il tempo solare.\footnote{per dettagli si consulti
+ \url{http://it.wikipedia.org/wiki/Leap_second}.}
+
+I campi \var{tm\_min} e\var{tm\_hour} che indicano rispettivamente minuti ed
+ore hanno valori compresi rispettivamente fra 0 e 59 e fra 0 e 23. Il campo
+\var{tm\_mday} che indica il giorno del mese prevede invece un valore compreso
+fra 1 e 31, ma la \acr{glibc} supporta pure il valore 0 come indicazione
+dell'ultimo giorno del mese precedente. Il campo \var{tm\_mon} indica il mese
+dell'anno a partire da gennaio con valori compresi fra 0 e 11.
+
+I campi \var{tm\_wday} e \var{tm\_yday} indicano invece rispettivamente il
+giorno della settimana, a partire dalla Domenica, ed il giorno dell'anno, a
+partire del primo gennaio, ed hanno rispettivamente valori compresi fra 0 e 6
+e fra 0 e 365. L'anno espresso da \var{tm\_year} viene contato come numero di
+anni a partire dal 1900. Infine \var{tm\_isdst} è un valore che indica se per
+gli altri campi si intende come attiva l'ora legale ed influenza il
+comportamento di \func{mktime}.
+
Le funzioni per la gestione del \textit{broken-down time} sono varie e vanno
da quelle usate per convertire gli altri formati in questo, usando o meno
l'ora locale o il tempo universale, a quelle per trasformare il valore di un
-tempo in una stringa contenente data ed ora, i loro prototipi sono:
-\begin{functions}
- \headdecl{time.h}
- \funcdecl{char *\funcd{asctime}(const struct tm *tm)}
- Produce una stringa con data e ora partendo da un valore espresso in
- \textit{broken-down time}.
-
- \funcdecl{char *\funcd{ctime}(const time\_t *timep)}
- Produce una stringa con data e ora partendo da un valore espresso in
- in formato \type{time\_t}.
-
- \funcdecl{struct tm *\funcd{gmtime}(const time\_t *timep)}
- Converte il \textit{calendar time} dato in formato \type{time\_t} in un
- \textit{broken-down time} espresso in UTC.
+tempo in una stringa contenente data ed ora. Le prime due funzioni,
+\funcd{asctime} e \funcd{ctime} servono per poter stampare in forma leggibile
+un tempo, i loro prototipi sono:
- \funcdecl{struct tm *\funcd{localtime}(const time\_t *timep)}
- Converte il \textit{calendar time} dato in formato \type{time\_t} in un
- \textit{broken-down time} espresso nell'ora locale.
+\begin{funcproto}{
+\fhead{time.h}
+\fdecl{char * asctime(const struct tm *tm)}
+\fdesc{Converte un \textit{broken-down time} in una stringa.}
+\fdecl{char * ctime(const time\_t *timep)}
+\fdesc{Converte un \textit{calendar time} in una stringa.}
+}
- \funcdecl{time\_t \funcd{mktime}(struct tm *tm)}
- Converte il \textit{broken-down time} in formato \type{time\_t}.
-
- \bodydesc{Tutte le funzioni restituiscono un puntatore al risultato in caso
- di successo e \val{NULL} in caso di errore, tranne che \func{mktime} che
- restituisce direttamente il valore o -1 in caso di errore.}
-\end{functions}
+{Le funzioni ritornano un puntatore al risultato in caso di successo e
+ \val{NULL} per un errore, \var{errno} non viene modificata.}
+\end{funcproto}
-\begin{figure}[!htb]
- \footnotesize \centering
- \begin{minipage}[c]{\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}
+Le funzioni prendono rispettivamente come argomenti i puntatori ad una
+struttura \struct{tm} contenente un \textit{broken-down time} o ad una
+variabile di tipo \type{time\_t} che esprime il \textit{calendar time},
+restituendo il puntatore ad una stringa che esprime la data, usando le
+abbreviazioni standard di giorni e mesi in inglese, nella forma:
+\begin{Example}
+Sun Apr 29 19:47:44 2012\n"
+\end{Example}
+
+Nel caso di \func{ctime} la funzione tiene conto della eventuale impostazione
+di una \itindex{timezone} \textit{timezone} e effettua una chiamata preventiva
+a \func{tzset} (che vedremo a breve), in modo che la data espressa tenga conto
+del fuso orario. In realtà \func{ctime} è banalmente definita in termini di
+\func{asctime} come \code{asctime(localtime(t)}.
+
+Dato che l'uso di una stringa statica rende le funzioni non
+\index{funzioni!rientranti} rientranti POSIX.1c e SUSv2 prevedono due
+sostitute \index{funzioni!rientranti} rientranti, il cui nome è al solito
+ottenuto aggiungendo un \code{\_r}, che prendono un secondo argomento
+\code{char *buf}, in cui l'utente deve specificare il buffer su cui la stringa
+deve essere copiata (deve essere di almeno 26 caratteri).
+
+Per la conversione fra \textit{broken-down time} e \textit{calendar time} sono
+invece disponibili altre tre funzioni, \funcd{gmtime}, \funcd{localtime} e
+\funcd{mktime} i cui prototipi sono:
+
+\begin{funcproto}{
+\fdecl{struct tm * gmtime(const time\_t *timep)}
+\fdesc{Converte un \textit{calendar time} in un \textit{broken-down time} in
+ UTC.}
+\fdecl{struct tm * localtime(const time\_t *timep)}
+\fdesc{Converte un \textit{calendar time} in un \textit{broken-down time}
+ nell'ora locale.}
+\fdecl{time\_t mktime(struct tm *tm)}
+\fdesc{Converte un \textit{broken-down time} in un \textit{calendar time}.}
+}
+
+{Le funzioni ritornano un puntatore al risultato in caso di successo e
+ \val{NULL} per un errore, tranne tranne che \func{mktime} che restituisce
+ direttamente il valore o $-1$ in caso di errore, \var{errno} non viene
+ modificata.}
+\end{funcproto}
+Le le prime funzioni, \func{gmtime}, \func{localtime} servono per convertire
+il tempo in \textit{calendar time} specificato da un argomento di tipo
+\type{time\_t} restituendo un \textit{broken-down time} con il puntatore ad
+una struttura \struct{tm}. La prima effettua la conversione senza tenere conto
+del fuso orario, esprimendo la data in tempo coordinato universale (UTC), cioè
+l'ora di Greenwich, mentre \func{localtime} usa l'ora locale e per questo
+effettua una chiamata preventiva a \func{tzset}.
-Le prime due funzioni, \func{asctime} e \func{ctime} servono per poter
-stampare in forma leggibile un tempo; esse restituiscono il puntatore ad una
-stringa, allocata staticamente, nella forma:
-\begin{verbatim}
-"Wed Jun 30 21:49:08 1993\n"
-\end{verbatim}
-e impostano anche la variabile \var{tzname} con l'informazione della
-\textit{time zone} corrente; \func{ctime} è banalmente definita in termini di
-\func{asctime} come \code{asctime(localtime(t)}. Dato che l'uso di una stringa
-statica rende le funzioni non \index{funzioni!rientranti} rientranti POSIX.1c
-e SUSv2 prevedono due sostitute \index{funzioni!rientranti} rientranti, il cui
-nome è al solito ottenuto aggiungendo un \code{\_r}, che prendono un secondo
-argomento \code{char *buf}, in cui l'utente deve specificare il buffer su cui
-la stringa deve essere copiata (deve essere di almeno 26 caratteri).
-
-Le altre tre funzioni, \func{gmtime}, \func{localtime} e \func{mktime} servono
-per convertire il tempo dal formato \type{time\_t} a quello di \struct{tm} e
-viceversa; \func{gmtime} effettua la conversione usando il tempo coordinato
-universale (UTC), cioè l'ora di Greenwich; mentre \func{localtime} usa l'ora
-locale; \func{mktime} esegue la conversione inversa.
-
-Anche in questo caso le prime due funzioni restituiscono l'indirizzo di una
+Anche in questo caso le due funzioni restituiscono l'indirizzo di una
struttura allocata staticamente, per questo sono state definite anche altre
due versioni \index{funzioni!rientranti} rientranti (con la solita estensione
\code{\_r}), che prevedono un secondo argomento \code{struct tm *result},
fornito dal chiamante, che deve preallocare la struttura su cui sarà
-restituita la conversione.
-
-Come mostrato in fig.~\ref{fig:sys_tm_struct} il \textit{broken-down time}
-permette di tenere conto anche della differenza fra tempo universale e ora
-locale, compresa l'eventuale ora legale. Questo viene fatto attraverso le tre
-\index{variabili!globali} variabili globali mostrate in
-fig.~\ref{fig:sys_tzname}, cui si accede quando si include
-\headfile{time.h}. Queste variabili vengono impostate quando si chiama una
-delle precedenti funzioni di conversione, oppure invocando direttamente la
-funzione \funcd{tzset}, il cui prototipo è:
-\begin{prototype}{sys/timex.h}
-{void tzset(void)}
-
- Imposta le variabili globali della \textit{time zone}.
-
- \bodydesc{La funzione non ritorna niente e non dà errori.}
-\end{prototype}
+restituita la conversione. La versione rientrante di \func{localtime} però non
+effettua la chiamata preventiva a \func{tzset} che deve essere eseguita a cura
+dell'utente.
+
+Infine \func{mktime} esegue la conversione di un \textit{broken-down time} a
+partire da una struttura \struct{tm} restituendo direttamente un valore di
+tipo \type{time\_t} con il \textit{calendar time}. La funzione ignora i campi
+\var{tm\_wday} e \var{tm\_yday} e per gli altri campi normalizza eventuali
+valori fuori degli intervalli specificati in precedenza: se cioè si indica un
+12 per \var{tm\_mon} si prenderà il gennaio dell'anno successivo. Inoltre la
+funzione tiene conto del valore di \var{tm\_isdst} per effettuare le
+correzioni relative al fuso orario: un valore positivo indica che deve essere
+tenuta in conto l'ora legale, un valore nullo che non deve essere applicata
+nessuna correzione, un valore negativo che si deve far ricorso alle
+informazioni relative al proprio fuso orario per determinare lo stato dell'ora
+legale.
+
+La funzione inoltre modifica i valori della struttura \struct{tm} in forma di
+\itindex{value~result~argument} \textit{value result argument}, normalizzando
+i valori dei vari campi, impostando i valori risultanti per \var{tm\_wday} e
+\var{tm\_yday} e assegnando a \var{tm\_isdst} il valore (positivo o nullo)
+corrispondente allo stato dell'ora legale. La funzione inoltre provvede ad
+impostare il valore della \index{variabili!globali} variabile globale
+\var{tzname}.
-La funzione inizializza le variabili di fig.~\ref{fig:sys_tzname} a partire
-dal valore della variabile di ambiente \envvar{TZ}, se quest'ultima non è
-definita verrà usato il file \conffile{/etc/localtime}.
+\itindend{calendar~time}
\begin{figure}[!htb]
\footnotesize
\centering
- \begin{minipage}[c]{\textwidth}
+ \begin{minipage}[c]{.75\textwidth}
\includestruct{listati/time_zone_var.c}
\end{minipage}
\normalsize
\caption{Le \index{variabili!globali} variabili globali usate per la
- gestione delle \textit{time zone}.}
+ gestione delle \itindex{timezone} \textit{timezone}.}
\label{fig:sys_tzname}
\end{figure}
-La variabile \var{tzname} contiene due stringhe, che indicano i due nomi
-standard della \textit{time zone} corrente. La prima è il nome per l'ora
-solare, la seconda per l'ora legale.\footnote{anche se sono indicati come
- \code{char *} non è il caso di modificare queste stringhe.} La variabile
-\var{timezone} indica la differenza di fuso orario in secondi, mentre
-\var{daylight} indica se è attiva o meno l'ora legale.
+Come accennato l'uso del \textit{broken-down time} permette di tenere conto
+anche della differenza fra tempo universale e ora locale, compresa l'eventuale
+ora legale. Questo viene fatto dalle funzioni di conversione grazie alle
+informazioni riguardo la propria \itindex{timezone} \textit{timezone}
+mantenute nelle tre \index{variabili!globali} variabili globali mostrate in
+fig.~\ref{fig:sys_tzname}, cui si si può accedere direttamente includendo
+\headfile{time.h}. Come illustrato queste variabili vengono impostate
+internamente da alcune delle delle precedenti funzioni di conversione, ma lo
+si può fare esplicitamente chiamando direttamente la funzione \funcd{tzset},
+il cui prototipo è:
+
+\begin{funcproto}{
+\fhead{sys/timex.h}
+\fdecl{void tzset(void)}
+\fdesc{Imposta le variabili globali della \textit{timezone}.}
+}
+
+{La funzione non ritorna niente e non dà errori.}
+\end{funcproto}
+
+La funzione inizializza le variabili di fig.~\ref{fig:sys_tzname} a partire
+dal valore della variabile di ambiente \envvar{TZ}, se quest'ultima non è
+definita verrà usato il file \conffile{/etc/localtime}. La variabile
+\var{tzname} contiene due stringhe, che indicano i due nomi standard della
+\itindex{timezone} \textit{timezone} corrente. La prima è il nome per l'ora
+solare, la seconda per l'ora legale. Anche se in fig.~\ref{fig:sys_tzname}
+sono indicate come \code{char *} non è il caso di modificare queste
+stringhe. La variabile \var{timezone} indica la differenza di fuso orario in
+secondi, mentre \var{daylight} indica se è attiva o meno l'ora legale.
Benché la funzione \func{asctime} fornisca la modalità più immediata per
stampare un tempo o una data, la flessibilità non fa parte delle sue
caratteristiche; quando si vuole poter stampare solo una parte (l'ora, o il
giorno) di un tempo si può ricorrere alla più sofisticata \funcd{strftime},
il cui prototipo è:
-\begin{prototype}{time.h}
-{size\_t strftime(char *s, size\_t max, const char *format,
+
+\begin{funcproto}{
+\fhead{time.h}
+\fdecl{size\_t strftime(char *s, size\_t max, const char *format,
const struct tm *tm)}
-
-Stampa il tempo \param{tm} nella stringa \param{s} secondo il formato
-\param{format}.
-
- \bodydesc{La funzione ritorna il numero di caratteri stampati in \param{s},
- altrimenti restituisce 0.}
-\end{prototype}
-
-La funzione converte opportunamente il tempo \param{tm} in una stringa di
-testo da salvare in \param{s}, purché essa sia di dimensione, indicata da
-\param{size}, sufficiente. I caratteri generati dalla funzione vengono
-restituiti come valore di ritorno, ma non tengono conto del terminatore
-finale, che invece viene considerato nel computo della dimensione; se
-quest'ultima è eccessiva viene restituito 0 e lo stato di \param{s} è
-indefinito.
+\fdesc{Crea una stringa con una data secondo il formato indicato.}
+}
+
+{La funzione ritorna il numero di caratteri inseriti nella stringa \param{s}
+ oppure $0$, \var{errno} non viene modificata.}
+\end{funcproto}
+
+
+La funzione converte il \textit{broken-down time} indicato nella struttura
+puntata dall'argomento \param{tm} in una stringa di testo da salvare
+all'indirizzo puntato dall'argomento \param{s}, purché essa sia di dimensione
+inferiore al massimo indicato dall'argomento \param{max}. Il numero di
+caratteri generati dalla funzione viene restituito come valore di ritorno,
+senza tener però conto del terminatore finale, che invece viene considerato
+nel computo della dimensione. Se quest'ultima è eccessiva viene restituito 0 e
+lo stato di \param{s} è indefinito.
\begin{table}[htb]
\footnotesize
\var{\%X}&\texttt{18:40:50} & L'ora.\\
\var{\%y}&\texttt{02} & Anno nel secolo.\\
\var{\%Y}&\texttt{2002} & Anno.\\
- \var{\%Z}&\texttt{CEST} & Nome della \textit{timezone}.\\
+ \var{\%Z}&\texttt{CEST} & Nome della \itindex{timezone}
+ \textit{timezone}.\\
\var{\%\%}&\texttt{\%} & Il carattere \%.\\
\hline
\end{tabular}
Il risultato della funzione è controllato dalla stringa di formato
\param{format}, tutti i caratteri restano invariati eccetto \texttt{\%} che
-viene utilizzato come modificatore; alcuni\footnote{per la precisione quelli
- definiti dallo standard ANSI C, che sono anche quelli riportati da POSIX.1;
- le \acr{glibc} provvedono tutte le estensioni introdotte da POSIX.2 per il
- comando \cmd{date}, i valori introdotti da SVID3 e ulteriori estensioni GNU;
- l'elenco completo dei possibili valori è riportato nella pagina di manuale
- della funzione.} dei possibili valori che esso può assumere sono riportati
-in tab.~\ref{tab:sys_strftime_format}. La funzione tiene conto anche della
-presenza di una localizzazione per stampare in maniera adeguata i vari nomi.
+viene utilizzato come modificatore. Alcuni dei possibili valori che esso può
+assumere sono riportati in tab.~\ref{tab:sys_strftime_format}.\footnote{per la
+ precisione si sono riportati definiti dallo standard ANSI C, che sono anche
+ quelli ripresi in POSIX.1; le \acr{glibc} forniscono anche le estensioni
+ introdotte da POSIX.2 per il comando \cmd{date}, i valori introdotti da
+ SVID3 e ulteriori estensioni GNU; l'elenco completo dei possibili valori è
+ riportato nella pagina di manuale della funzione.} La funzione tiene conto
+anche delle eventuali impostazioni di localizzazione per stampare i vari nomi
+in maniera adeguata alla lingua scelta, e con le convenzioni nazionali per i
+formati di data ed ora.
+
+Infine per effettuare l'operazione di conversione inversa, da una stringa ad
+un \textit{broken-down time}, si può utilizzare la funzione \funcd{strptime},
+il cui prototipo è:
+
+\begin{funcproto}{
+\fhead{time.h}
+\fdecl{char *strptime(const char *s, const char *format, struct tm *tm)}
+\fdesc{Converte una stringa con in un \textit{broken-down time} secondo un
+ formato.}
+}
+
+{La funzione ritorna il puntatore al primo carattere non processato della
+ stringa o al terminatore finale qualora questa sia processata interamente,
+ \var{errno} non viene modificata.}
+\end{funcproto}
+
+La funzione processa la stringa puntata dall'argomento \param{s} da sinistra a
+destra, utilizzando il formato contenuto nella stringa puntata
+dall'argomento \param{format}, avvalorando volta volta i corrispondenti campi
+della struttura puntata dall'argomento \param{tm}. La scansione si interrompe
+immediatamente in caso di mancata corrispondenza a quanto indicato nella
+stringa di formato, che usa una sintassi analoga a quella già vista per
+\func{strftime}. La funzione supporta i modificatori di
+tab.~\ref{tab:sys_strftime_format} più altre estensioni, ma per i dettagli a
+questo riguardo si rimanda alla lettura della pagina di manuale.
+
+Si tenga presente comunque che anche in caso di scansione completamente
+riuscita la funzione sovrascrive soltanto i campi di \param{tm} indicati dal
+formato, la struttura originaria infatti non viene inizializzati e gli altri
+campi restano ai valori che avevano in precedenza.
-\itindend{calendar~time}
+\itindend{broken-down~time}
\section{La gestione degli errori}
\label{sec:sys_errors}
unix-like il kernel non avvisa mai direttamente un processo dell'occorrenza di
un errore nell'esecuzione di una funzione, ma di norma questo viene riportato
semplicemente usando un opportuno valore di ritorno della funzione invocata.
-Inoltre il sistema di classificazione degli errori è basato sull'architettura
-a processi, e presenta una serie di problemi nel caso lo si debba usare con i
-\itindex{thread} \textit{thread}.
+Inoltre il sistema di classificazione degli errori è stato progettato
+sull'architettura a processi, e presenta una serie di problemi nel caso lo si
+debba usare con i \itindex{thread} \textit{thread}.
\subsection{La variabile \var{errno}}
Quasi tutte le funzioni delle librerie del C sono in grado di individuare e
riportare condizioni di errore, ed è una norma fondamentale di buona
-programmazione controllare \textbf{sempre} che le funzioni chiamate si siano
+programmazione controllare \textsl{sempre} che le funzioni chiamate si siano
concluse correttamente.
In genere le funzioni di libreria usano un valore speciale per indicare che
-c'è stato un errore. Di solito questo valore è -1 o un puntatore nullo o la
-costante \val{EOF} (a seconda della funzione); ma questo valore segnala solo
-che c'è stato un errore, non il tipo di errore.
+c'è stato un errore. Di solito questo valore, a seconda della funzione, è $-1$
+o un puntatore nullo o la costante \val{EOF}; ma questo valore segnala solo
+che c'è stato un errore, e non il tipo di errore.
Per riportare il tipo di errore il sistema usa \index{variabili!globali} la
-variabile globale \var{errno},\footnote{l'uso di una variabile globale può
- comportare alcuni problemi (ad esempio nel caso dei \itindex{thread}
- \textit{thread}) ma lo standard ISO C consente anche di definire \var{errno}
- come un \textit{modifiable lvalue}, quindi si può anche usare una macro, e
- questo è infatti il modo usato da Linux per renderla locale ai singoli
- \itindex{thread} \textit{thread}.} definita nell'header \headfile{errno.h};
-la variabile è in genere definita come \direct{volatile} dato che può essere
-cambiata in modo asincrono da un segnale (si veda sez.~\ref{sec:sig_sigchld}
-per un esempio, ricordando quanto trattato in sez.~\ref{sec:proc_race_cond}),
-ma dato che un gestore di segnale scritto bene salva e ripristina il valore
-della variabile, di questo non è necessario preoccuparsi nella programmazione
-normale.
+variabile globale \var{errno}, definita nell'header \headfile{errno.h}. Come
+accennato l'uso di una variabile globale può comportare problemi nel caso dei
+\itindex{thread} \textit{thread}, ma lo standard ISO C consente anche di
+definire \var{errno} come un cosiddetto ``\textit{modifiable lvalue}'', cosa
+che consente di usare anche una macro, e questo è infatti il metodo usato da
+Linux per renderla locale ai singoli \itindex{thread} \textit{thread}.
+
+La variabile è in genere definita come \direct{volatile} dato che può essere
+cambiata in modo asincrono da un segnale, per un esempio si veda
+sez.~\ref{sec:sig_sigchld} ricordando quanto trattato in
+sez.~\ref{sec:proc_race_cond}). Dato che un gestore di segnale scritto bene si
+cura di salvare e ripristinare il valore della variabile all'uscita, nella
+programmazione normale, quando si può fare l'assunzione che i gestori di
+segnali siano ben scritti, di questo non è necessario preoccuparsi.
I valori che può assumere \var{errno} sono riportati in app.~\ref{cha:errors},
nell'header \headfile{errno.h} sono anche definiti i nomi simbolici per le
-costanti numeriche che identificano i vari errori; essi iniziano tutti per
-\val{E} e si possono considerare come nomi riservati. In seguito faremo sempre
-riferimento a tali valori, quando descriveremo i possibili errori restituiti
-dalle funzioni. Il programma di esempio \cmd{errcode} stampa il codice
-relativo ad un valore numerico con l'opzione \cmd{-l}.
+costanti numeriche che identificano i vari errori che abbiamo citato fin
+dall'inizio nelle descrizioni delle funzioni. Essi iniziano tutti per \val{E}
+e si possono considerare come nomi riservati, per questo abbiamo sempre fatto
+riferimento a questi nomi, e lo faremo più avanti quando descriveremo i
+possibili errori restituiti dalle funzioni. Il programma di esempio
+\cmd{errcode} stampa il codice relativo ad un valore numerico con l'opzione
+\cmd{-l}.
Il valore di \var{errno} viene sempre impostato a zero all'avvio di un
-programma, gran parte delle funzioni di libreria impostano \var{errno} ad un
-valore diverso da zero in caso di errore. Il valore è invece indefinito in
-caso di successo, perché anche se una funzione ha successo, può chiamarne
-altre al suo interno che falliscono, modificando così \var{errno}.
+programma, e la gran parte delle funzioni di libreria impostano \var{errno} ad
+un valore diverso da zero in caso di errore. Il valore è invece indefinito in
+caso di successo, perché anche se una funzione di libreria ha successo,
+potrebbe averne chiamate altre al suo interno che potrebbero essere fallite
+anche senza compromettere il risultato finale, modificando però \var{errno}.
Pertanto un valore non nullo di \var{errno} non è sintomo di errore (potrebbe
essere il risultato di un errore precedente) e non lo si può usare per
-determinare quando o se una chiamata a funzione è fallita. La procedura da
-seguire è sempre quella di controllare \var{errno} immediatamente dopo aver
-verificato il fallimento della funzione attraverso il suo codice di ritorno.
+determinare quando o se una chiamata a funzione è fallita. La procedura
+corretta da seguire per identificare un errore è sempre quella di controllare
+\var{errno} immediatamente dopo aver verificato il fallimento della funzione
+attraverso il suo codice di ritorno.
\subsection{Le funzioni \func{strerror} e \func{perror}}
riportare in opportuni messaggi le condizioni di errore verificatesi. La
prima funzione che si può usare per ricavare i messaggi di errore è
\funcd{strerror}, il cui prototipo è:
-\begin{prototype}{string.h}{char *strerror(int errnum)}
- Restituisce una stringa con il messaggio di errore relativo ad
- \param{errnum}.
-
- \bodydesc{La funzione ritorna il puntatore ad una stringa di errore.}
-\end{prototype}
+\begin{funcproto}{
+\fhead{string.h}
+\fdecl{char *strerror(int errnum)}
+\fdesc{Restituisce una stringa con un messaggio di errore.}
+}
+
+{La funzione ritorna il puntatore alla stringa con il messaggio di errore,
+ \var{errno} non viene modificato.}
+\end{funcproto}
La funzione ritorna il puntatore alla stringa contenente il messaggio di
errore corrispondente al valore di \param{errnum}, se questo non è un valore
valido verrà comunque restituita una stringa valida contenente un messaggio
-che dice che l'errore è sconosciuto, e \var{errno} verrà modificata assumendo
-il valore \errval{EINVAL}.
-
-In generale \func{strerror} viene usata passando \var{errno} come argomento,
-ed il valore di quest'ultima non verrà modificato. La funzione inoltre tiene
-conto del valore della variabile di ambiente \envvar{LC\_MESSAGES} per usare
-le appropriate traduzioni dei messaggi d'errore nella localizzazione presente.
-
-La funzione utilizza una stringa statica che non deve essere modificata dal
-programma; essa è utilizzabile solo fino ad una chiamata successiva a
-\func{strerror} o \func{perror}, nessun'altra funzione di libreria tocca
-questa stringa. In ogni caso l'uso di una stringa statica rende la funzione
-non \index{funzioni!rientranti} rientrante, per cui nel caso si usino i
-\itindex{thread} \textit{thread} le librerie forniscono\footnote{questa
- funzione è la versione prevista dalle \acr{glibc}, ed effettivamente
- definita in \headfile{string.h}, ne esiste una analoga nello standard SUSv3
- (quella riportata dalla pagina di manuale), che restituisce \code{int} al
- posto di \code{char *}, e che tronca la stringa restituita a
- \param{size}.} una apposita versione \index{funzioni!rientranti} rientrante
-\funcd{strerror\_r}, il cui prototipo è:
-\begin{prototype}{string.h}
- {char * strerror\_r(int errnum, char *buf, size\_t size)}
-
- Restituisce una stringa con il messaggio di errore relativo ad
- \param{errnum}.
-
- \bodydesc{La funzione restituisce l'indirizzo del messaggio in caso di
- successo e \val{NULL} in caso di errore; nel qual caso \var{errno}
- assumerà i valori:
+che dice che l'errore è sconosciuto nella forma. La versione della \acr{glibc}
+non modifica il valore di \var{errno} in caso di errore, ma questo non è detto
+valga per altri sistemi in quanto lo standard POSIX.1-2001 permette che ciò
+avvenga. Non si faccia affidamento su questa caratteristica se si vogliono
+scrivere programmi portabili.
+
+In generale \func{strerror} viene usata passando direttamente \var{errno} come
+argomento, ed il valore di quest'ultima non verrà modificato. La funzione
+inoltre tiene conto del valore della variabile di ambiente
+\envvar{LC\_MESSAGES} per usare le appropriate traduzioni dei messaggi
+d'errore nella localizzazione presente.
+
+La funzione \func{strerror} utilizza una stringa statica che non deve essere
+modificata dal programma; essa è utilizzabile solo fino ad una chiamata
+successiva a \func{strerror} o \func{perror} e nessun'altra funzione di
+libreria tocca questa stringa. In ogni caso l'uso di una stringa statica rende
+la funzione non \index{funzioni!rientranti} rientrante, per cui nel caso si
+usino i \itindex{thread} \textit{thread} la \acr{glibc} fornisce una apposita
+versione \index{funzioni!rientranti} rientrante \funcd{strerror\_r}, il cui
+prototipo è:
+
+\begin{funcproto}{
+\fhead{string.h}
+\fdecl{char * strerror\_r(int errnum, char *buf, size\_t size)}
+\fdesc{Restituisce una stringa con un messaggio di errore.}
+}
+
+{La funzione ritorna l'indirizzo del messaggio in caso di successo e
+ \val{NULL} per un errore, nel qual caso \var{errno} assumerà uno dei valori:
\begin{errlist}
\item[\errcode{EINVAL}] si è specificato un valore di \param{errnum} non
valido.
\item[\errcode{ERANGE}] la lunghezza di \param{buf} è insufficiente a
contenere la stringa di errore.
- \end{errlist}}
-\end{prototype}
-\noindent
+ \end{errlist}
+}
+\end{funcproto}
+
+Si tenga presente che questa è la versione prevista normalmente nella
+\acr{glibc}, ed effettivamente definita in \headfile{string.h}, ne esiste una
+analoga nello standard SUSv3 (riportata anche nella pagina di manuale), che
+restituisce \code{int} al posto di \code{char *}, e che tronca la stringa
+restituita a \param{size}, a cui si accede definendo le opportune macro (per
+le quali si rimanda alla lettura della pagina di manuale).
La funzione è analoga a \func{strerror} ma restituisce la stringa di errore
nel buffer \param{buf} che il singolo \itindex{thread} \textit{thread} deve
allocare autonomamente per evitare i problemi connessi alla condivisione del
buffer statico. Il messaggio è copiato fino alla dimensione massima del
-buffer, specificata dall'argomento
-\param{size}, che deve comprendere pure il carattere di terminazione;
-altrimenti la stringa viene troncata.
+buffer, specificata dall'argomento \param{size}, che deve comprendere pure il
+carattere di terminazione; altrimenti la stringa risulterà troncata.
Una seconda funzione usata per riportare i codici di errore in maniera
automatizzata sullo standard error è \funcd{perror}, il cui prototipo è:
-\begin{prototype}{stdio.h}{void perror(const char *message)}
- Stampa il messaggio di errore relativo al valore corrente di \var{errno}
- sullo standard error; preceduto dalla stringa \param{message}.
-\end{prototype}
+
+\begin{funcproto}{
+\fhead{stdio.h}
+\fdecl{void perror(const char *message)}
+\fdesc{Stampa un messaggio di errore personalizzato.}
+}
+
+{La funzione non ritorna nulla e non modifica \var{errno}.}
+\end{funcproto}
+
I messaggi di errore stampati sono gli stessi di \func{strerror}, (riportati
in app.~\ref{cha:errors}), e, usando il valore corrente di \var{errno}, si
riferiscono all'ultimo errore avvenuto. La stringa specificata con
-\param{message} viene stampato prima del messaggio d'errore, seguita dai due
-punti e da uno spazio, il messaggio è terminato con un a capo.
-
-Il messaggio può essere riportato anche usando le due
+\param{message} viene stampata prima del messaggio d'errore, consentono una
+personalizzazione (ad esempio l'indicazione del contesto in cui si è
+verificato), seguita dai due punti e da uno spazio, il messaggio è terminato
+con un a capo. Il messaggio può essere riportato anche usando le due
\index{variabili!globali} variabili globali:
\includecodesnip{listati/errlist.c}
dichiarate in \headfile{errno.h}. La prima contiene i puntatori alle stringhe
di errore indicizzati da \var{errno}; la seconda esprime il valore più alto
-per un codice di errore, l'utilizzo di questa stringa è sostanzialmente
-equivalente a quello di \func{strerror}.
+per un codice di errore, l'utilizzo di una di queste stringhe è
+sostanzialmente equivalente a quello di \func{strerror}.
\begin{figure}[!htbp]
\footnotesize \centering
In fig.~\ref{fig:sys_err_mess} è riportata la sezione attinente del codice del
programma \cmd{errcode}, che può essere usato per stampare i messaggi di
-errore e le costanti usate per identificare i singoli errori; il sorgente
+errore e le costanti usate per identificare i singoli errori. Il sorgente
completo del programma è allegato nel file \file{ErrCode.c} e contiene pure la
gestione delle opzioni e tutte le definizioni necessarie ad associare il
valore numerico alla costante simbolica. In particolare si è riportata la
La prima estensione consiste in due variabili, \code{char *
program\_invocation\_name} e \code{char * program\_invocation\_short\_name}
-servono per ricavare il nome del programma; queste sono utili quando si deve
-aggiungere il nome del programma (cosa comune quando si ha un programma che
-non viene lanciato da linea di comando e salva gli errori in un file di log)
-al messaggio d'errore. La prima contiene il nome usato per lanciare il
-programma (ed è equivalente ad \code{argv[0]}); la seconda mantiene solo il
-nome del programma (senza eventuali directory in testa).
-
-Uno dei problemi che si hanno con l'uso di \func{perror} è che non c'è
-flessibilità su quello che si può aggiungere al messaggio di errore, che può
-essere solo una stringa. In molte occasioni invece serve poter scrivere dei
-messaggi con maggiore informazione; ad esempio negli standard di
-programmazione GNU si richiede che ogni messaggio di errore sia preceduto dal
-nome del programma, ed in generale si può voler stampare il contenuto di
-qualche variabile; per questo le \acr{glibc} definiscono la funzione
-\funcd{error}, il cui prototipo è:
-\begin{prototype}{stdio.h}
-{void error(int status, int errnum, const char *format, ...)}
-
-Stampa un messaggio di errore formattato.
-
-\bodydesc{La funzione non restituisce nulla e non riporta errori.}
-\end{prototype}
+che consentono di ricavare il nome del proprio programma. Queste sono utili
+quando si deve aggiungere il nome del programma al messaggio d'errore, cosa
+comune quando si ha un programma che non viene lanciato da linea di comando e
+salva gli errori in un file di log. La prima contiene il nome usato per
+lanciare il programma dalla shell ed in sostanza è equivalente ad
+\code{argv[0]}; la seconda mantiene solo il nome del programma eliminando
+eventuali directory qualora questo sia stato lanciato con un
+\textit{pathname}.
+
+Una seconda estensione cerca di risolvere uno dei problemi che si hanno con
+l'uso di \func{perror}, dovuto al fatto che non c'è flessibilità su quello che
+si può aggiungere al messaggio di errore, che può essere solo una stringa. In
+molte occasioni invece serve poter scrivere dei messaggi con maggiori
+informazioni. Ad esempio negli standard di programmazione GNU si richiede che
+ogni messaggio di errore sia preceduto dal nome del programma, ed in generale
+si può voler stampare il contenuto di qualche variabile per facilitare la
+comprensione di un eventuale problema. Per questo le \acr{glibc} definiscono
+la funzione \funcd{error}, il cui prototipo è:
+
+\begin{funcproto}{
+\fhead{stdio.h}
+\fdecl{void error(int status, int errnum, const char *format, ...)}
+\fdesc{Stampa un messaggio di errore formattato.}
+}
+
+{La funzione non ritorna nulla e non riporta errori.}
+\end{funcproto}
La funzione fa parte delle estensioni GNU per la gestione degli errori,
-l'argomento \param{format} prende la stessa sintassi di \func{printf}, ed i
-relativi argomenti devono essere forniti allo stesso modo, mentre
-\param{errnum} indica l'errore che si vuole segnalare (non viene quindi usato
-il valore corrente di \var{errno}); la funzione stampa sullo standard error il
+l'argomento \param{format} segue la stessa sintassi di \func{printf} (vedi
+sez.~\ref{sec:file_formatted_io}), ed i relativi argomenti devono essere
+forniti allo stesso modo, mentre \param{errnum} indica l'errore che si vuole
+segnalare (non viene quindi usato il valore corrente di \var{errno}).
+
+La funzione stampa sullo \itindex{standard~error} \textit{standard error} il
nome del programma, come indicato dalla \index{variabili!globali} variabile
globale \var{program\_name}, seguito da due punti ed uno spazio, poi dalla
-stringa generata da
-\param{format} e dagli argomenti seguenti, seguita da due punti ed uno spazio
-infine il messaggio di errore relativo ad \param{errnum}, il tutto è terminato
-da un a capo.
+stringa generata da \param{format} e dagli argomenti seguenti, seguita da due
+punti ed uno spazio infine il messaggio di errore relativo ad \param{errnum},
+il tutto è terminato da un a capo.
Il comportamento della funzione può essere ulteriormente controllato se si
definisce una variabile \var{error\_print\_progname} come puntatore ad una
Un'altra funzione per la stampa degli errori, ancora più sofisticata, che
prende due argomenti aggiuntivi per indicare linea e file su cui è avvenuto
l'errore è \funcd{error\_at\_line}; il suo prototipo è:
-\begin{prototype}{stdio.h}
-{void error\_at\_line(int status, int errnum, const char *fname,
- unsigned int lineno, const char *format, ...)}
-Stampa un messaggio di errore formattato.
+\begin{funcproto}{
+\fhead{stdio.h}
+\fdecl{void error\_at\_line(int status, int errnum, const char *fname,
+ unsigned int lineno, \\
+\phantom{void error\_at\_line(}const char *format, ...)}
+\fdesc{Stampa un messaggio di errore formattato.}
+}
+
+{La funzione non ritorna nulla e non riporta errori.}
+\end{funcproto}
-\bodydesc{La funzione non restituisce nulla e non riporta errori.}
-\end{prototype}
\noindent ed il suo comportamento è identico a quello di \func{error} se non
per il fatto che, separati con il solito due punti-spazio, vengono inseriti un
nome di file indicato da \param{fname} ed un numero di linea subito dopo la
% LocalWords: memory mlockall MAP LOCKED shmctl MSGQUEUE attr NICE nice MADV
% LocalWords: madvise WILLNEED RTPRIO sched setscheduler setparam scheduling
% LocalWords: RTTIME execve kb prlimit pid new old ESRCH EUSERS refresh high
-
+% LocalWords: resolution HRT jiffies strptime
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "gapil"
%%% End:
-% LocalWords: resolution HRT jiffies
projects / gapil.git / commitdiff