Transizione \macro{} -> \const{}, \errcode{}, \val{}
[gapil.git] / filestd.tex
index 80c641b..670e55b 100644 (file)
@@ -231,7 +231,7 @@ Le funzioni che si possono usare per aprire uno stream sono solo tre:
   specificato da \param{stream}, se questo è già aperto prima lo chiude.
   
   \bodydesc{Le funzioni ritornano un puntatore valido in caso di successo e
-    \macro{NULL} in caso di errore, in tal caso \var{errno} assumerà il valore
+    \val{NULL} in caso di errore, in tal caso \var{errno} assumerà il valore
     ricevuto dalla funzione sottostante di cui è fallita l'esecuzione.
   
     Gli errori pertanto possono essere quelli di \code{malloc} per tutte
@@ -304,7 +304,7 @@ Le \acr{glibc} supportano alcune estensioni, queste devono essere sempre
 indicate dopo aver specificato il \param{mode} con uno dei valori di
 \tabref{tab:file_fopen_mode}. L'uso del carattere \texttt{x} serve per
 evitare di sovrascrivere un file già esistente (è analoga all'uso
-dell'opzione \macro{O\_EXCL} in \func{open}), se il file specificato già
+dell'opzione \const{O\_EXCL} in \func{open}), se il file specificato già
 esiste e si aggiunge questo carattere a \param{mode} la \func{fopen}
 fallisce. 
 
@@ -323,7 +323,7 @@ non viene duplicato e verr
 
 I nuovi file saranno creati secondo quanto visto in
 \secref{sec:file_ownership} ed avranno i permessi di accesso impostati al
-valore \macro{S\_IRUSR|S\_IWUSR|S\_IRGRP|S\_IWGRP|S\_IROTH|S\_IWOTH} (pari a
+valore \code{S\_IRUSR|S\_IWUSR|S\_IRGRP|S\_IWGRP|S\_IROTH|S\_IWOTH} (pari a
 \var{0666}) modificato secondo il valore di \acr{umask} per il processo (si
 veda \secref{sec:file_umask}).
 
@@ -350,8 +350,8 @@ Uno stream viene chiuso con la funzione \func{fclose} il cui prototipo 
 \begin{prototype}{stdio.h}{int fclose(FILE *stream)}
   Chiude lo stream \param{stream}. 
   
-  \bodydesc{Restituisce 0 in caso di successo e \macro{EOF} in caso di errore,
-    nel qual caso imposta \var{errno} a \macro{EBADF} se il file descriptor
+  \bodydesc{Restituisce 0 in caso di successo e \val{EOF} in caso di errore,
+    nel qual caso imposta \var{errno} a \const{EBADF} se il file descriptor
     indicato da \param{stream} non è valido, o uno dei valori specificati
     dalla sottostante funzione che è fallita (\func{close}, \func{write} o
     \func{fflush}).}
@@ -366,11 +366,11 @@ una \func{sync} (vedi \secref{sec:file_sync}).
 
 Linux supporta anche una altra funzione, \func{fcloseall}, come estensione GNU
 implementata dalle \acr{glibc}, accessibile avendo definito
-\macro{\_GNU\_SOURCE}, il suo prototipo è:
+\const{\_GNU\_SOURCE}, il suo prototipo è:
 \begin{prototype}{stdio.h}{int fcloseall(void)}
   Chiude tutti gli stream. 
   
-  \bodydesc{Restituisce 0 se non ci sono errori ed \macro{EOF} altrimenti.}
+  \bodydesc{Restituisce 0 se non ci sono errori ed \val{EOF} altrimenti.}
 \end{prototype}
 \noindent la funzione esegue lo scarico dei dati bufferizzati in uscita
 e scarta quelli in ingresso, chiudendo tutti i file. Questa funzione è
@@ -402,7 +402,7 @@ A differenza dell'interfaccia dei file descriptor, con gli stream il
 raggiungimento della fine del file è considerato un errore, e viene
 notificato come tale dai valori di uscita delle varie funzioni. Nella
 maggior parte dei casi questo avviene con la restituzione del valore
-intero (di tipo \ctyp{int}) \macro{EOF}\footnote{la costante deve essere
+intero (di tipo \ctyp{int}) \val{EOF}\footnote{la costante deve essere
   negativa, le \acr{glibc} usano -1, altre implementazioni possono avere
   valori diversi.}  definito anch'esso nell'header \file{stdlib.h}.
 
@@ -596,7 +596,7 @@ rispettivi prototipi sono:
   
   \bodydesc{Tutte queste funzioni leggono un byte alla volta, che viene
     restituito come intero; in caso di errore o fine del file il valore
-    di ritorno è \macro{EOF}.}
+    di ritorno è \val{EOF}.}
 \end{functions}
 
 A parte \func{getchar}, che si usa in genere per leggere un carattere da
@@ -636,7 +636,7 @@ byte restituiscono un carattere in formato esteso (cio
   \funcdecl{wint\_t getwchar(void)} Equivalente a \code{getwc(stdin)}.
   
   \bodydesc{Tutte queste funzioni leggono un carattere alla volta, in
-    caso di errore o fine del file il valore di ritorno è \macro{WEOF}.}
+    caso di errore o fine del file il valore di ritorno è \const{WEOF}.}
 \end{functions}
 
 Per scrivere un carattere si possono usare tre funzioni analoghe alle
@@ -655,14 +655,14 @@ precedenti usate per leggere: \func{putc}, \func{fputc} e
   
   \bodydesc{Le funzioni scrivono sempre un carattere alla volta, il cui
     valore viene restituito in caso di successo; in caso di errore o
-    fine del file il valore di ritorno è \macro{EOF}.}
+    fine del file il valore di ritorno è \val{EOF}.}
 \end{functions}
 
 Tutte queste funzioni scrivono sempre un byte alla volta, anche se
 prendono come parametro un \ctyp{int} (che pertanto deve essere ottenuto
 con un cast da un \ctyp{unsigned char}). Anche il valore di ritorno è
 sempre un intero; in caso di errore o fine del file il valore di ritorno
-è \macro{EOF}.
+è \val{EOF}.
 
 Come nel caso dell'I/O binario le \acr{glibc} provvedono per ciascuna
 delle funzioni precedenti, come estensione GNU, una seconda funzione, il
@@ -680,12 +680,12 @@ loro prototipi sono:
   \funcdecl{int putw(int w, FILE *stream)} Scrive la parola \param{w} su
   \param{stream}.
   
-  \bodydesc{Le funzioni restituiscono la parola \param{w}, o \macro{EOF}
+  \bodydesc{Le funzioni restituiscono la parola \param{w}, o \val{EOF}
     in caso di errore o di fine del file.}
 \end{functions}
 \noindent l'uso di queste funzioni è deprecato in favore dell'uso di
 \func{fread} e \func{fwrite}, in quanto non è possibile distinguere il
-valore -1 da una condizione di errore che restituisce \macro{EOF}.
+valore -1 da una condizione di errore che restituisce \val{EOF}.
 
 Uno degli usi più frequenti dell'input/output a caratteri è nei programmi di
 \textit{parsing} in cui si analizza il testo; in questo contesto diventa utile
@@ -703,7 +703,7 @@ lettura si chiama \func{ungetc} ed il suo prototipo 
     char}, sullo stream \param{stream}.
 
   \bodydesc{La funzione ritorna \param{c} in caso di successo e
-  \macro{EOF} in caso di errore.}
+  \val{EOF} in caso di errore.}
 \end{prototype}
 \noindent benché lo standard ANSI C preveda che l'operazione possa
 essere ripetuta per un numero arbitrario di caratteri, alle
@@ -716,8 +716,8 @@ si 
 prima di usare \func{ungetc}, ma di norma la funzione è intesa per
 essere usata per rimandare indietro l'ultimo carattere letto.
 
-Nel caso \param{c} sia un \macro{EOF} la funzione non fa nulla, e
-restituisce sempre \macro{EOF}; così si può usare \func{ungetc} anche
+Nel caso \param{c} sia un \val{EOF} la funzione non fa nulla, e
+restituisce sempre \val{EOF}; così si può usare \func{ungetc} anche
 con il risultato di una lettura alla fine del file.
 
 Se si è alla fine del file si può comunque rimandare indietro un
@@ -754,7 +754,7 @@ prototipi sono:
   massimo di \param{size} byte.
   
   \bodydesc{Le funzioni restituiscono l'indirizzo \param{string} in caso
-    di successo o \macro{NULL} in caso di errore.}
+    di successo o \val{NULL} in caso di errore.}
 \end{functions}
 
 Entrambe le funzioni effettuano la lettura (dal file specificato \func{fgets},
@@ -763,7 +763,7 @@ carattere \textit{newline}, \verb|'\n'|, quello mappato sul tasto di ritorno a
 capo della tastiera), ma \func{gets} sostituisce \verb|'\n'| con uno zero,
 mentre \func{fgets} aggiunge uno zero dopo il \textit{newline}, che resta
 dentro la stringa. Se la lettura incontra la fine del file (o c'è un errore)
-viene restituito un \macro{NULL}, ed il buffer \param{buf} non viene toccato.
+viene restituito un \val{NULL}, ed il buffer \param{buf} non viene toccato.
 L'uso di \func{gets} è deprecato e deve essere assolutamente evitato; la
 funzione infatti non controlla il numero di byte letti, per cui nel caso la
 stringa letta superi le dimensioni del buffer, si avrà un \textit{buffer
@@ -803,7 +803,7 @@ rispettivi prototipi sono:
   \param{stream} la linea \param{string}.
   
   \bodydesc{Le funzioni restituiscono un valore non negativo in caso di
-    successo o \macro{EOF} in caso di errore.}
+    successo o \val{EOF} in caso di errore.}
 \end{functions}
 
 Dato che in questo caso si scrivono i dati in uscita \func{puts} non ha i
@@ -826,7 +826,7 @@ per leggere e scrivere caratteri estesi, i loro prototipi sono:
   linea \param{ws} di caratteri estesi sul file \param{stream}.
   
   \bodydesc{Le funzioni ritornano rispettivamente \param{ws} o un numero
-    non negativo in caso di successo e \macro{NULL} o \macro{EOF} in
+    non negativo in caso di successo e \val{NULL} o \val{EOF} in
     caso di errore o fine del file.}
 \end{functions}
 \noindent il cui comportamento è identico a quello di \func{fgets} e
@@ -856,7 +856,7 @@ che eccede le dimensioni del buffer.
 Per questo motivo le \acr{glibc} prevedono, come estensione GNU, due
 nuove funzioni per la gestione dell'input/output di linea, il cui uso
 permette di risolvere questi problemi. L'uso di queste funzioni deve
-essere attivato definendo la macro \macro{\_GNU\_SOURCE} prima di
+essere attivato definendo la macro \const{\_GNU\_SOURCE} prima di
 includere \file{stdio.h}. La prima delle due, \func{getline}, serve per
 leggere una linea terminata da un newline esattamente allo stesso modo
 di \func{fgets}, il suo prototipo è:
@@ -887,7 +887,7 @@ usati dei \textit{value result argument}, passando dei puntatori anzich
 i valori delle variabili, secondo la tecnica spiegata in
 \secref{sec:proc_var_passing}).
 
-Se si passa alla funzione l'indirizzo di un puntatore impostato a \macro{NULL}
+Se si passa alla funzione l'indirizzo di un puntatore impostato a \val{NULL}
 e \var{*n} è zero, la funzione provvede da sola all'allocazione della memoria
 necessaria a contenere la linea. In tutti i casi si ottiene dalla funzione un
 puntatore all'inizio del testo della linea letta. Un esempio di codice può
@@ -1024,12 +1024,12 @@ direttiva, ed uno degli specificatori di conversione (riportati in
     \textbf{Valore} & \textbf{Significato}\\
     \hline
     \hline
-    \cmd{\#} & Chiede la conversione in forma alternativa. \\
-    \cmd{0}  & La conversione è riempita con zeri alla sinistra del valore.\\
-    \cmd{-}  & La conversione viene allineata a sinistra sul bordo del campo.\\
-    \cmd{' '}& Mette uno spazio prima di un numero con segno di valore 
+    \val{\#} & Chiede la conversione in forma alternativa. \\
+    \val{0}  & La conversione è riempita con zeri alla sinistra del valore.\\
+    \val{-}  & La conversione viene allineata a sinistra sul bordo del campo.\\
+    \val{' '}& Mette uno spazio prima di un numero con segno di valore 
                positivo\\
-    \cmd{+}  & Mette sempre il segno ($+$ o $-$) prima di un numero.\\
+    \val{+}  & Mette sempre il segno ($+$ o $-$) prima di un numero.\\
     \hline
   \end{tabular}
   \caption{I valori dei flag per il formato di \func{printf}}
@@ -1044,12 +1044,12 @@ generale essa 
 % [n. parametro $] [flag] [[larghezza] [. precisione]] [tipo] conversione
 \end{verbatim}
 \end{center}
-in cui tutti i valori tranne il \cmd{\%} e lo specificatore di conversione
+in cui tutti i valori tranne il \val{\%} e lo specificatore di conversione
 sono opzionali (e per questo sono indicati fra parentesi quadre); si possono
 usare più elementi opzionali, nel qual caso devono essere specificati in
 questo ordine:
 \begin{itemize*}
-\item uno specificatore del parametro da usare (terminato da un \cmd{\$}),
+\item uno specificatore del parametro da usare (terminato da un \val{\$}),
 \item uno o più flag (i cui valori possibili sono riassunti in
   \tabref{tab:file_format_flag}) che controllano il formato di stampa della
   conversione,
@@ -1125,7 +1125,7 @@ tramite il parametro \param{ap}. Per poter far questo ovviamente la lista dei
 parametri dovrà essere opportunamente trattata (l'argomento è esaminato in
 \secref{sec:proc_variadic}), e dopo l'esecuzione della funzione l'argomento
 \param{ap} non sarà più utilizzabile (in generale dovrebbe essere eseguito un
-\macro{va\_end(ap)} ma in Linux questo non è necessario). 
+\code{va\_end(ap)} ma in Linux questo non è necessario). 
 
 Come per \func{sprintf} anche per \func{vsprintf} esiste una analoga
 \func{vsnprintf} che pone un limite sul numero di caratteri che vengono
@@ -1140,7 +1140,7 @@ scritti sulla stringa di destinazione:
 
 Per eliminare alla radice questi problemi, le \acr{glibc} supportano una
 specifica estensione GNU che alloca dinamicamente tutto lo spazio necessario;
-l'estensione si attiva al solito definendo \macro{\_GNU\_SOURCE}, le due
+l'estensione si attiva al solito definendo \const{\_GNU\_SOURCE}, le due
 funzioni sono:
 \begin{functions}
   \headdecl{stdio.h} 
@@ -1189,7 +1189,7 @@ famiglia \func{scanf}; fra queste le tre pi
   \bodydesc{Le funzioni ritornano il numero di elementi assegnati. Questi
     possono essere in numero inferiore a quelli specificati, ed anche zero.
     Quest'ultimo valore significa che non si è trovata corrispondenza. In caso
-    di errore o fine del file viene invece restituito \macro{EOF}.}
+    di errore o fine del file viene invece restituito \val{EOF}.}
 \end{functions}
 \noindent e come per le analoghe funzioni di scrittura esistono le relative
 \func{vscanf}, \func{vfscanf} \func{vsscanf} che usano un puntatore ad una
@@ -1339,7 +1339,7 @@ il prototipo della funzione 
   
   \bodydesc{Restituisce il numero del file descriptor in caso di successo, e
     -1 qualora \param{stream} non sia valido, nel qual caso imposta
-    \var{errno} a \macro{EBADF}.}
+    \var{errno} a \const{EBADF}.}
 \end{prototype}
 \noindent ed in questo modo diventa possibile usare direttamente \func{fcntl}.
 
@@ -1423,7 +1423,7 @@ stato allocato e rimanere disponibile per tutto il tempo in cui si opera sullo
 stream. In genere conviene allocarlo con \func{malloc} e disallocarlo dopo la
 chiusura del file; ma fintanto che il file è usato all'interno di una
 funzione, può anche essere usata una variabile automatica. In \file{stdio.h} è
-definita la macro \macro{BUFSIZ}, che indica le dimensioni generiche del
+definita la macro \const{BUFSIZ}, che indica le dimensioni generiche del
 buffer di uno stream; queste vengono usate dalla funzione \func{setbuf}.  Non
 è detto però che tale dimensione corrisponda sempre al valore ottimale (che
 può variare a seconda del dispositivo).
@@ -1445,9 +1445,9 @@ coincidano con quelle su cui viene effettuato l'I/O.
       \textbf{Valore} & \textbf{Modalità} \\
       \hline
       \hline
-      \macro{\_IONBF} & \textit{unbuffered}\\
-      \macro{\_IOLBF} & \textit{line buffered}\\
-      \macro{\_IOFBF} & \textit{fully buffered}\\
+      \const{\_IONBF} & \textit{unbuffered}\\
+      \const{\_IOLBF} & \textit{line buffered}\\
+      \const{\_IOFBF} & \textit{fully buffered}\\
       \hline
     \end{tabular}
   \caption{Valori del parametro \param{mode} di \func{setvbuf} 
@@ -1456,7 +1456,7 @@ coincidano con quelle su cui viene effettuato l'I/O.
 \end{table}
 
 Per evitare che \func{setvbuf} imposti il buffer basta passare un valore
-\macro{NULL} per \param{buf} e la funzione ignorerà il parametro \param{size}
+\val{NULL} per \param{buf} e la funzione ignorerà il parametro \param{size}
 usando il buffer allocato automaticamente dal sistema.  Si potrà comunque
 modificare la modalità di bufferizzazione, passando in \param{mode} uno degli
 opportuni valori elencati in \tabref{tab:file_stream_buf_mode}. Qualora si
@@ -1470,11 +1470,11 @@ e \func{setlinebuf}; i loro prototipi sono:
   \headdecl{stdio.h} 
   
   \funcdecl{void setbuf(FILE *stream, char *buf)} Disabilita la
-  bufferizzazione se \param{buf} è \macro{NULL}, altrimenti usa \param{buf}
-  come buffer di dimensione \macro{BUFSIZ} in modalità \textit{fully buffered}.
+  bufferizzazione se \param{buf} è \val{NULL}, altrimenti usa \param{buf}
+  come buffer di dimensione \const{BUFSIZ} in modalità \textit{fully buffered}.
   
   \funcdecl{void setbuffer(FILE *stream, char *buf, size\_t size)} Disabilita
-  la bufferizzazione se \param{buf} è \macro{NULL}, altrimenti usa \param{buf}
+  la bufferizzazione se \param{buf} è \val{NULL}, altrimenti usa \param{buf}
   come buffer di dimensione \param{size} in modalità \textit{fully buffered}.
   
   \funcdecl{void setlinebuf(FILE *stream)} Pone lo stream in modalità
@@ -1503,17 +1503,17 @@ scelta, si pu
   
   Forza la scrittura di tutti i dati bufferizzati dello stream \param{stream}.
   
-  \bodydesc{Restituisce zero in caso di successo, ed \macro{EOF} in caso di
-    errore, impostando \var{errno} a \macro{EBADF} se \param{stream} non è
+  \bodydesc{Restituisce zero in caso di successo, ed \val{EOF} in caso di
+    errore, impostando \var{errno} a \const{EBADF} se \param{stream} non è
     aperto o non è aperto in scrittura, o ad uno degli errori di
     \func{write}.}
 \end{prototype}
 \noindent anche di questa funzione esiste una analoga
-\func{fflush\_unlocked}\footnote{accessibile definendo \macro{\_BSD\_SOURCE} o
-  \macro{\_SVID\_SOURCE} o \macro{\_GNU\_SOURCE}.} che non effettua il blocco
+\func{fflush\_unlocked}\footnote{accessibile definendo \const{\_BSD\_SOURCE} o
+  \const{\_SVID\_SOURCE} o \const{\_GNU\_SOURCE}.} che non effettua il blocco
 dello stream.
 
-Se \param{stream} è \macro{NULL} lo scarico dei dati è forzato per tutti gli
+Se \param{stream} è \val{NULL} lo scarico dei dati è forzato per tutti gli
 stream aperti. Esistono però circostanze, ad esempio quando si vuole essere
 sicuri che sia stato eseguito tutto l'output su terminale, in cui serve poter
 effettuare lo scarico dei dati solo per gli stream in modalità line buffered;
@@ -1535,7 +1535,7 @@ pendente; per questo si pu
  
   Cancella i buffer di input e di output dello stream \param{stream}.
   
-  \bodydesc{Restituisce zero in caso di successo, ed \macro{EOF} in caso di
+  \bodydesc{Restituisce zero in caso di successo, ed \val{EOF} in caso di
     errore.}
 \end{prototype}
 
@@ -1565,7 +1565,7 @@ Ci sono comunque situazioni in cui questo non basta, come quando un thread
 necessita di compiere più di una operazione sullo stream atomicamente, per
 questo motivo le librerie provvedono anche delle funzioni che permettono la
 gestione esplicita dei blocchi sugli stream; queste funzioni sono disponibili
-definendo \macro{\_POSIX\_THREAD\_SAFE\_FUNCTIONS} ed i loro prototipi sono:
+definendo \const{\_POSIX\_THREAD\_SAFE\_FUNCTIONS} ed i loro prototipi sono:
 \begin{functions}
   \headdecl{stdio.h}
   
@@ -1608,18 +1608,18 @@ prototipo 
   all'acquisizione implicita del blocco sullo stream.
 
   \bodydesc{Restituisce lo stato di locking interno dello stream con uno dei
-  valori \macro{FSETLOCKING\_INTERNAL} o \macro{FSETLOCKING\_BYCALLER}.}
+  valori \const{FSETLOCKING\_INTERNAL} o \const{FSETLOCKING\_BYCALLER}.}
 \end{prototype}
 
 La funzione imposta o legge lo stato della modalità di operazione di uno stream
 nei confronti del locking a seconda del valore specificato con \param{type},
 che può essere uno dei seguenti:
 \begin{basedescript}{\desclabelwidth{4.0cm}}
-\item[\macro{FSETLOCKING\_INTERNAL}] Lo stream userà da ora in poi il blocco
+\item[\const{FSETLOCKING\_INTERNAL}] Lo stream userà da ora in poi il blocco
   implicito predefinito.
-\item[\macro{FSETLOCKING\_BYCALLER}] Al ritorno della funzione sarà l'utente a
+\item[\const{FSETLOCKING\_BYCALLER}] Al ritorno della funzione sarà l'utente a
   dover gestire da solo il locking dello stream.
-\item[\macro{FSETLOCKING\_QUERY}] Restituisce lo stato corrente della modalità
+\item[\const{FSETLOCKING\_QUERY}] Restituisce lo stato corrente della modalità
   di blocco dello stream.
 \end{basedescript}