filestd.tex

   1  \chapter{I file: l'interfaccia standard ANSI C}
   2 \label{cha:files_std_interface}
   3
   4 Esamineremo in questo capitolo l'interfaccia standard ANSI C per i file,
   5 quella che viene comunemente detta interfaccia degli \textit{stream}.
   6 Dopo una breve sezione introduttiva tratteremo le funzioni base per la
   7 gestione dell'input/output, mentre tratteremo le caratteristiche più avanzate
   8 dell'interfaccia nell'ultima sezione.
   9
  10
  11 \section{Introduzione}
  12 \label{sec:file_stream_intro}
  13
  14 Come visto in \capref{cha:file_unix_interface} le operazioni di I/O sui file
  15 sono gestibili a basso livello con l'interfaccia standard unix, che ricorre
  16 direttamente alle system call messe a disposizione dal kernel.
  17
  18 Questa interfaccia però non provvede le funzionalità previste dallo standard
  19 ANSI C, che invece sono realizzate attraverso opportune funzioni di libreria,
  20 queste, insieme alle altre funzioni definite dallo standard, vengono a
  21 costituire il nucleo\footnote{queste funzioni sono state implementate la prima
  22   volta da Ritchie nel 1976 e da allora sono rimaste sostanzialmente
  23   immutate.} delle \acr{glibc}.
  24
  25
  26 \subsection{I \textit{file stream}}
  27 \label{sec:file_stream}
  28
  29 Come più volte ribadito l'interfaccia dei file descriptor è una interfaccia di
  30 basso livello, che non provvede nessuna forma di formattazione dei dati e
  31 nessuna forma di bufferizzazione per ottimizzare le operazioni di I/O.
  32
  33 In \textit{Advanced Programming in the Unix Environment} Stevens descrive una
  34 serie di test sull'influenza delle dimensioni del blocco di dati (il parametro
  35 \param{buf} di \func{read} e \func{write}) nell'efficienza nelle operazioni di
  36 I/O con i file descriptor, evidenziando come le prestazioni ottimali si
  37 ottengano a partire da dimensioni del buffer dei dati pari a quelle dei
  38 blocchi del filesystem (il valore dato dal campo \var{st\_blksize} di
  39 \var{fstat}).
  40
  41 Se il programmatore non si cura di effettuare le operazioni in blocchi di
  42 dimensioni adeguate, le prestazioni sono inferiori.  La caratteristica
  43 principale dell'interfaccia degli stream è che essa provvede da sola alla
  44 gestione dei dettagli della bufferizzazione e all'esecuzione delle operazioni
  45 di lettura e scrittura in blocchi di dimensioni appropriate all'ottenimento
  46 della massima efficienza.
  47
  48 Per questo motivo l'interfaccia viene chiamata anche interfaccia dei
  49 \textit{file stream}, dato che non è più necessario doversi preoccupare
  50 dei dettagli della comunicazione con il tipo di hardware sottostante
  51 (come nel caso della dimensione dei blocchi del filesystem), ed un file
  52 può essere sempre considerato come composto da un flusso continuo (da
  53 cui il nome \textit{stream}) di dati.
  54
  55 A parte i dettagli legati alla gestione delle operazioni di lettura e
  56 scrittura (sia per quel che riguarda la bufferizzazione, che le
  57 formattazioni), i file stream restano del tutto equivalenti ai file descriptor
  58 (sui quali sono basati), ed in particolare continua a valere quanto visto in
  59 \secref{sec:file_sharing} a proposito dell'accesso condiviso ed in
  60 \secref{sec:file_access_control} per il controllo di accesso.
  61
  62
  63 \subsection{Gli oggetti \type{FILE}}
  64 \label{sec:file_FILE}
  65
  66 Per ragioni storiche la struttura di dati che rappresenta uno stream è stata
  67 chiamata \type{FILE}, questi oggetti sono creati dalle funzioni di libreria e
  68 contengono tutte le informazioni necessarie a gestire le operazioni sugli
  69 stream, come la posizione corrente, lo stato del buffer e degli indicatori di
  70 stato e di fine del file.
  71
  72 Per questo motivo gli utenti non devono mai utilizzare direttamente o
  73 allocare queste strutture, ma usare sempre puntatori del tipo \type{FILE
  74   *} ottenuti dalla libreria stessa (tanto che in certi casi il termine
  75 di puntatore a file è diventato sinonimo di stream).  Tutte le funzioni
  76 della libreria che operano sui file accettano come parametri solo
  77 variabili di questo tipo, che diventa accessibile includendo l'header
  78 file \file{stdio.h}.
  79
  80
  81
  82 \subsection{Gli stream standard}
  83 \label{sec:file_std_stream}
  84
  85 Ai tre file descriptor standard (vedi \secref{sec:file_std_descr})
  86 aperti per ogni processo, corrispondono altrettanti stream, che
  87 rappresentano i canali standard di input/output prestabiliti; anche
  88 questi tre stream sono identificabili attraverso dei nomi simbolici
  89 definiti nell'header \file{stdio.h} che sono:
  90
  91 \begin{itemize}
  92 \item \var{FILE * stdin} Lo \textit{standard input} cioè lo stream da
  93   cui il processo riceve ordinariamente i dati in ingresso. Normalmente
  94   è associato dalla shell all'input del terminale e prende i caratteri
  95   dalla tastiera.
  96 \item \var{FILE * stdout} Lo \textit{standard input} cioè lo stream su
  97   cui il processo invia ordinariamente i dati in uscita. Normalmente è
  98   associato dalla shell all'output del terminale e scrive sullo schermo.
  99 \item \var{FILE * stderr} Lo \textit{standard input} cioè lo stream su
 100   cui il processo è supposto inviare i messaggi di errore. Normalmente
 101   anch'esso è associato dalla shell all'output del terminale e scrive
 102   sullo schermo.
 103 \end{itemize}
 104
 105 Nelle \acr{glibc} \var{stdin}, \var{stdout} e \var{stderr} sono
 106 effettivamente tre variabili di tipo \type{FILE *} che possono essere
 107 usate come tutte le altre, ad esempio si può effettuare una redirezione
 108 dell'output di un programma con il semplice codice:
 109 \begin{lstlisting}[labelstep=0,frame=,indent=1cm]{}
 110     fclose (stdout);
 111     stdout = fopen ("standard-output-file", "w");
 112 \end{lstlisting}
 113 ma in altri sistemi queste variabili possono essere definite da macro, e
 114 se si hanno problemi di portabilità e si vuole essere sicuri, diventa
 115 opportuno usare la funzione \func{freopen}.
 116
 117
 118 \subsection{Le modalità di bufferizzazione}
 119 \label{sec:file_buffering}
 120
 121 La bufferizzazione è una delle caratteristiche principali della
 122 interfaccia degli stream; lo scopo è quello di ridurre al minimo il
 123 numero di system call (\func{read} o \func{write}) eseguite nelle
 124 operazioni di input/output. Questa funzionalità è assicurata
 125 automaticamente dalla libreria, ma costituisce anche una degli aspetti
 126 più comunemente fraintesi, in particolare per quello che riguarda
 127 l'aspetto della scrittura dei dati sul file.
 128
 129 I caratteri che vengono scritti su uno stream normalmente vengono
 130 accumulati in un buffer e poi trasmessi in blocco in maniera asincrona
 131 rispetto alla scrittura (quello che viene chiamato lo \textsl{scarico}
 132 dei dati, dall'inglese \textit{flush}) tutte le volte che il buffer
 133 viene riempito. Un comportamento analogo avviene anche in lettura (cioè
 134 dal file viene letto un blocco di dati, anche se se ne sono richiesti
 135 una quantità inferiore), ma la cosa ovviamente ha rilevanza inferiore,
 136 dato che i dati letti sono sempre gli stessi; in caso di scrittura
 137 invece, quando si ha un accesso contemporaneo allo stesso file (ad
 138 esempio da parte di un altro processo) si potranno vedere solo le parti
 139 effettivamente scritte, e non quelle ancora presenti nel buffer.
 140
 141 Allo stesso modo, se si sta facendo dell'input/output interattivo
 142 bisognerà tenere presente le caratteristiche delle operazioni di scarico
 143 dei dati, poiché non è detto che ad una scrittura sullo stream
 144 corrisponda una immediata scrittura sul dispositivo.
 145
 146 Per rispondere ad esigenze diverse, lo standard definisce tre distinte
 147 modalità in cui può essere eseguita la bufferizzazione, delle quali
 148 occorre essere ben consapevoli, specie in caso di lettura e scrittura da
 149 dispositivi interattivi:
 150 \begin{itemize}
 151 \item \textit{unbuffered}: in questo caso non c'è bufferizzazione ed i
 152   caratteri vengono trasmessi direttamente al file non appena possibile
 153   (effettuando immediatamente una \func{write}).
 154 \item \textit{line buffered}: in questo caso i caratteri vengono
 155   normalmente trasmessi al file in blocco ogni volta che viene
 156   incontrato un carattere di \textit{newline} (il carattere ASCII
 157   \verb|\n|).
 158 \item \textit{fully buffered}: in questo caso i caratteri vengono
 159   trasmessi da e verso il file in blocchi di dimensione opportuna.
 160 \end{itemize}
 161
 162 Lo standard ANSI C specifica inoltre che lo standard output e lo
 163 standard input siano aperti in modalità \textit{fully buffered} quando
 164 non fanno riferimento ad un dispositivo interattivo, e che lo standard
 165 error non sia mai aperto in modalità \textit{fully buffered}.
 166
 167 Linux, come BSD e SVr4, specifica il comportamento di default in maniera
 168 ancora più precisa, e cioè impone che lo standard error sia sempre
 169 \textit{unbuffered} (in modo che i messaggi di errore siano mostrati il più
 170 rapidamente possibile) e che standard input e standard output siano aperti in
 171 modalità \textit{line buffered} quando sono associati ad un terminale (od
 172 altro dispositivo interattivo) ed in modalità \textit{fully buffered}
 173 altrimenti.
 174
 175 Il comportamento specificato per standard input e standard output vale anche
 176 per tutti i nuovi stream aperti da un processo; la selezione comunque avviene
 177 automaticamente, e la libreria apre lo stream nella modalità più opportuna a
 178 seconda del file o del dispositivo scelto.
 179
 180 La modalità \textit{line buffered} è quella che necessita di maggiori
 181 chiarimenti e attenzioni per quel che concerne il suo funzionamento. Come già
 182 accennato nella descrizione, \emph{di norma} i dati vengono inviati al kernel
 183 alla ricezione di un carattere di a capo; questo non è vero in tutti i casi,
 184 infatti, dato che le dimensioni del buffer usato dalle librerie sono fisse, se
 185 le si eccedono si può avere uno scarico dei dati anche prima che sia stato
 186 inviato un carattere di \textit{newline}.
 187
 188 Un secondo punto da tenere presente, particolarmente quando si ha a che fare
 189 con I/O interattivo, è che quando si effettua una lettura su uno stream che
 190 comporta l'accesso al kernel\footnote{questo vuol dire sempre se lo stream da
 191   cui si legge è in modalità \textit{unbuffered}.} viene anche eseguito lo
 192 scarico di tutti i buffer degli stream in scrittura.
 193
 194 In \secref{sec:file_buffering_ctrl} vedremo come la libreria definisca delle
 195 opportune funzioni per controllare le modalità di bufferizzazione e lo scarico
 196 dei dati.
 197
 198
 199
 200 \section{Funzioni base}
 201 \label{sec:file_ansi_base_func}
 202
 203 Esamineremo in questa sezione le funzioni base dell'interfaccia degli stream,
 204 analoghe a quelle di \secref{sec:file_base_func} per i file descriptor. In
 205 particolare vedremo come aprire, leggere, scrivere e cambiare la posizione
 206 corrente in uno stream.
 207
 208
 209 \subsection{Apertura e chiusura di uno stream}
 210 \label{sec:file_fopen}
 211
 212 Le funzioni che si possono usare per aprire uno stream sono solo
 213 tre\footnote{\func{fopen} e \func{freopen} fanno parte dello standard
 214   ANSI C, \func{fdopen} è parte dello standard POSIX.1.}, i loro
 215 prototipi sono:
 216 \begin{functions}
 217   \headdecl{stdio.h}
 218   \funcdecl{FILE * fopen(const char * path, const char *mode)}
 219   Apre il file specificato da \param{path}.
 220   \funcdecl{FILE * fdopen(int fildes, const char * mode)}
 221   Associa uno stream al file descriptor \param{fildes}.
 222   \funcdecl{FILE * freopen(const char * path, const char * mode, FILE *
 223   stream)}
 224   Apre il file specificato da \param{path} associandolo allo stream
 225   specificato da \param{stream}, se questo è già aperto prima lo chiude.
 226
 227   Le funzioni ritornano un puntatore valido in caso di successo e \macro{NULL}
 228   in caso di errore, in tal caso \var{errno} viene settata al valore ricevuto
 229   dalla funzione sottostante di cui è fallita l'esecuzione.
 230
 231   Gli errori pertanto possono essere quelli di \func{malloc} per tutte e tre
 232   le funzioni, quelli \func{open} per \func{fopen}, quelli di \func{fcntl} per
 233   \func{fdopen} e quelli di \func{fopen}, \func{fclose} e \func{fflush} per
 234   \func{freopen}.
 235 \end{functions}
 236
 237 Normalmente la funzione che si usa per aprire uno stream è \func{fopen},
 238 essa apre il file specificato nella modalità specificata da
 239 \param{mode}, che è una stringa che deve iniziare con almeno uno dei
 240 valori indicati in \tabref{tab:file_fopen_mode} (sono possibili varie
 241 estensioni che vedremo in seguito).
 242
 243 L'uso più comune di \func{freopen} è per redirigere uno dei tre file
 244 standard (vedi \secref{sec:file_std_stream}): il file \param{path} viene
 245 associato a \param{stream} e se questo è uno stream già aperto viene
 246 preventivamente chiuso.
 247
 248 Infine \func{fdopen} viene usata per associare uno stream ad un file
 249 descriptor esistente ottenuto tramite una altra funzione (ad esempio con
 250 una \func{open}, una \func{dup}, o una \func{pipe}) e serve quando si
 251 vogliono usare gli stream con file come le fifo o i socket, che non
 252 possono essere aperti con le funzioni delle librerie standard del C.
 253
 254 \begin{table}[htb]
 255   \centering
 256   \begin{tabular}[c]{|l|p{8cm}|}
 257     \hline
 258     \textbf{Valore} & \textbf{Significato}\\
 259     \hline
 260     \hline
 261     \texttt{r} & Il file viene aperto, l'accesso viene posto in sola
 262     lettura, lo stream è posizionato all'inizio del file.\\
 263     \texttt{r+} & Il file viene aperto, l'accesso viene posto in lettura e
 264     scrittura, lo stream è posizionato all'inizio del file. \\
 265 %    \hline
 266     \texttt{w} & Il file viene aperto e troncato a lunghezza nulla (o
 267     creato se non esiste), l'accesso viene posto in sola scrittura, lo
 268     stream è posizionato all'inizio del file.\\
 269     \texttt{w+} & Il file viene aperto e troncato a lunghezza nulla (o
 270     creato se non esiste), l'accesso viene posto in scrittura e lettura,
 271     lo stream è posizionato all'inizio del file.\\
 272 %    \hline
 273     \texttt{a} & Il file viene aperto (o creato se non esiste) in
 274     \textit{append mode}, l'accesso viene posto in sola scrittura. \\
 275     \texttt{a+} & Il file viene aperto (o creato se non esiste) in
 276     \textit{append mode}, l'accesso viene posto in lettura e scrittura. \\
 277     \hline
 278   \end{tabular}
 279   \caption{Modalità di apertura di uno stream dello standard ANSI C che
 280     sono sempre presenti in qualunque sistema POSIX}
 281   \label{tab:file_fopen_mode}
 282 \end{table}
 283
 284 In realtà lo standard ANSI C prevede un totale di 15 possibili valori
 285 diversi per \param{mode}, ma in \tabref{tab:file_fopen_mode} si sono
 286 riportati solo i sei valori effettivi, ad essi può essere aggiunto pure
 287 il carattere \func{b} (come ultimo carattere o nel mezzo agli altri per
 288 le stringhe di due caratteri) che in altri sistemi operativi serve a
 289 distinguere i file binari dai file di testo; in un sistema POSIX questa
 290 distinzione non esiste e il valore viene accettato solo per
 291 compatibilità, ma non ha alcun effetto.
 292
 293 Le \acr{glibc} supportano alcune estensioni, queste devono essere sempre
 294 indicate dopo aver specificato il \param{mode} con uno dei valori di
 295 \tabref{tab:file_fopen_mode}. L'uso del carattere \texttt{x} serve per
 296 evitare di sovrascrivere un file già esistente (è analoga all'uso
 297 dell'opzione \macro{O\_EXCL} in \func{open}), se il file specificato già
 298 esiste e si aggiunge questo carattere a \param{mode} la \func{fopen}
 299 fallisce.
 300
 301 Un'altra estensione serve a supportare la localizzazione, quando si
 302 aggiunge a \param{mode} una stringa della forma \verb|",ccs=STRING"| il
 303 valore \verb|STRING| è considerato il nome di una codifica dei caratteri
 304 e \func{fopen} marca il file per l'uso dei caratteri estesi e abilita le
 305 opportune funzioni di conversione in lettura e scrittura.
 306
 307 Inoltre nel caso si usi \func{fdopen} i valori specificati da
 308 \param{mode} devono essere compatibili con quelli con cui il file
 309 descriptor è stato aperto. Inoltre i modi \cmd{w} e \cmd{w+} non
 310 troncano il file. La posizione nello stream viene settata a quella
 311 corrente nel file descriptor, e le variabili di errore e di fine del
 312 file (vedi \secref{sec:file_io}) sono cancellate. Il file non viene
 313 duplicato e verrà chiuso alla chiusura dello stream.
 314
 315 I nuovi file saranno creati secondo quanto visto in
 316 \secref{sec:file_ownership} ed avranno i permessi di accesso settati al
 317 valore \macro{S\_IRUSR|S\_IWUSR|S\_IRGRP|S\_IWGRP|S\_IROTH|S\_IWOTH}
 318 (pari a \macro{0666}) modificato secondo il valore di \acr{umask} per il
 319 processo (si veda \secref{sec:file_umask}).
 320
 321 In caso di file aperti in lettura e scrittura occorre ricordarsi che c'è
 322 di messo una bufferizzazione; per questo motivo lo standard ANSI C
 323 richiede che ci sia una operazione di posizionamento fra una operazione
 324 di output ed una di input o viceversa (eccetto il caso in cui l'input ha
 325 incontrato la fine del file), altrimenti una lettura può ritornare anche
 326 il risultato di scritture precedenti l'ultima effettuata.
 327
 328 Per questo motivo è una buona pratica (e talvolta necessario) far seguire ad
 329 una scrittura una delle funzioni \func{fflush}, \func{fseek}, \func{fsetpos} o
 330 \func{rewind} prima di eseguire una rilettura; viceversa nel caso in cui si
 331 voglia fare una scrittura subito dopo aver eseguito una lettura occorre prima
 332 usare una delle funzioni \func{fseek}, \func{fsetpos} o \func{rewind}. Anche
 333 una operazione nominalmente nulla come \func{fseek(file, 0, SEEK\_CUR)} è
 334 sufficiente a garantire la sincronizzazione.
 335
 336 Una volta aperto lo stream, si può cambiare la modalità di bufferizzazione
 337 (vedi \secref{sec:file_buffering_ctrl}) fintanto che non si è effettuato
 338 alcuna operazione di I/O sul file.
 339
 340 Uno stream viene chiuso con la funzione \func{fclose} il cui prototipo è:
 341 \begin{prototype}{stdio.h}{int fclose(FILE * stream)}
 342   Chiude lo stream \param{stream}.
 343
 344   Restituisce 0 in caso di successo e \macro{EOF} in caso di errore, nel qual
 345   caso setta \var{errno} a \macro{EBADF} se il file descriptor indicato da
 346   \param{stream} non è valido, o uno dei valori specificati dalla sottostante
 347   funzione che è fallita (\func{close}, \func{write} o \func{fflush}).
 348 \end{prototype}
 349
 350 La funzione effettua uno scarico di tutti i dati presenti nei buffer di
 351 uscita e scarta tutti i dati in ingresso, se era stato allocato un
 352 buffer per lo stream questo verrà rilasciato. La funzione effettua lo
 353 scarico solo per i dati presenti nei buffer in user space usati dalle
 354 \acr{glibc}; se si vuole essere sicuri che il kernel forzi la scrittura
 355 su disco occorrerà effettuare una \func{sync}.
 356
 357 Linux supporta, come estensione implementata dalle \acr{glibc}, anche una
 358 altra funzione, \func{fcloseall}, che serve a chiudere tutti i file, il suo
 359 prototipo è:
 360 \begin{prototype}{stdio.h}{int fcloseall(void)}
 361   Chiude tutti gli stream.
 362
 363   Restituisce 0 se non ci sono errori ed \macro{EOF} altrimenti.
 364 \end{prototype}
 365 la funzione esegue lo scarico dei dati bufferizzati in uscita e scarta quelli
 366 in ingresso, chiudendo tutti i file. Questa funzione è provvista solo per i
 367 casi di emergenza, quando si è verificato un errore ed il programma deve
 368 essere abortito, ma si vuole compiere qualche altra operazione dopo aver
 369 chiuso i file e prima di uscire (si ricordi quanto visto in
 370 \secref{sec:proc_exit}).
 371
 372
 373 \subsection{Lettura e scrittura su uno stream}
 374 \label{sec:file_io}
 375
 376 Una delle caratteristiche più utili dell'interfaccia degli stream è la
 377 ricchezza delle funzioni disponibili per le operazioni di lettura e
 378 scrittura sui file. Sono infatti previste ben tre diverse modalità
 379 modalità di input/output non formattato:
 380 \begin{enumerate*}
 381 \item\textsl{binario} in cui legge/scrive un blocco di dati alla
 382   volta, vedi \secref{sec:file_binary_io}.
 383 \item\textsl{a caratteri} in cui si legge/scrive un carattere alla
 384   volta (con la bufferizzazione gestita automaticamente dalla libreria),
 385   vedi \secref{sec:file_char_io}.
 386 \item\textsl{di linea} in cui si legge/scrive una linea (terminata dal
 387   carattere di newline \verb|\n|) alla volta, vedi
 388   \secref{sec:file_line_io}.
 389 \end{enumerate*}
 390 ed inoltre la modalità di input/output formattato.
 391
 392 A differenza dell'interfaccia dei file descriptor, con gli stream il
 393 raggiungimento della fine del file è considerato un errore, e viene
 394 notificato come tale dai valori di uscita delle varie funzioni. Nella
 395 maggior parte dei casi questo avviene con la restituzione del valore
 396 intero (di tipo \type{int}) \macro{EOF}\footnote{la costante deve essere
 397   negativa, le \acr{glibc} usano -1, altre implementazioni possono avere
 398   valori diversi.}  definito anch'esso nell'header \func{stdlib.h}.
 399
 400 Dato che le funzioni dell'interfaccia degli stream sono funzioni di libreria
 401 che si appoggiano a delle system call, esse non settano direttamente la
 402 variabile \var{errno}, che mantiene il valore settato dalla system call che ha
 403 riportato l'errore.
 404
 405 Siccome la condizione di end-of-file è anch'essa segnalata come errore, nasce
 406 il problema di come distinguerla da un errore effettivo; basarsi solo sul
 407 valore di ritorno della funzione e controllare il valore di \var{errno}
 408 infatti non basta, dato che quest'ultimo potrebbe essere stato settato in una
 409 altra occasione, (si veda \secref{sec:sys_errno} per i dettagli del
 410 funzionamento di \var{errno}).
 411
 412 Per questo motivo tutte le implementazioni delle librerie standard
 413 mantengono per ogni stream almeno due flag all'interno dell'oggetto
 414 \type{FILE}, il flag di \textit{end-of-file}, che segnala che si è
 415 raggiunta la fine del file in lettura, e quello di errore, che segnala
 416 la presenza di un qualche errore nelle operazioni di input/output;
 417 questi due flag possono essere riletti dalle funzioni:
 418 \begin{functions}
 419   \headdecl{stdio.h}
 420   \funcdecl{int feof(FILE *stream)}
 421   Controlla il flag di end-of-file di \param{stream}.
 422   \funcdecl{int ferror(FILE *stream)}
 423   Controlla il flag di errore di \param{stream}.
 424
 425   Entrambe le funzioni ritornano un valore diverso da zero se i relativi
 426   flag sono settati.
 427 \end{functions}
 428 \noindent si tenga presente comunque che la lettura di questi flag segnala
 429 soltanto che c'è stato un errore, o che si è raggiunta la fine del file in una
 430 qualunque operazione sullo stream, il controllo quindi deve essere effettuato
 431 ogni volta che si chiama una funzione di libreria.
 432
 433 Entrambi i flag (di errore e di end-of-file) possono essere cancellati usando
 434 la funzione \func{clearerr}, il cui prototipo è:
 435 \begin{prototype}{stdio.h}{void clearerr( FILE *stream)}
 436   Cancella i flag di errore ed end-of-file di \param{stream}.
 437 \end{prototype}
 438 \noindent in genere si usa questa funziona una volta che si sia identificata e
 439 corretta la causa di un errore per evitare di mantenere i flag attivi,
 440 così da poter rilevare una successiva ulteriore condizione di errore.
 441
 442
 443 \subsection{Input/output binario}
 444 \label{sec:file_binary_io}
 445
 446 La prima modalità di input/output non formattato ricalca quella della
 447 interfaccia dei file descriptor, e provvede semplicemente la scrittura e
 448 la lettura dei dati da un buffer verso un file e viceversa. In generale
 449 questa è la modalità che si usa quando si ha a che fare con dati non
 450 formattati. Le due funzioni che si usano per l'I/O binario sono:
 451 \begin{functions}
 452   \headdecl{stdio.h}
 453
 454   \funcdecl{size\_t fread(void * ptr, size\_t size, size\_t nmemb, FILE
 455     * stream)}
 456
 457   \funcdecl{size\_t fwrite(const void * ptr, size\_t size, size\_t
 458     nmemb, FILE * stream)}
 459
 460   Le funzioni rispettivamente leggono e scrivono \param{nmemb} elementi
 461   di dimensione \param{size} dal buffer \param{ptr} al file
 462   \param{stream}.
 463
 464   Entrambe le funzioni ritornano il numero di elementi letti o scritti,
 465   in caso di errore o fine del file viene restituito un numero di
 466   elementi inferiore al richiesto.
 467 \end{functions}
 468
 469 In genere si usano queste funzioni quando si devono trasferire su file
 470 blocchi di dati binari in maniera compatta e veloce; un primo caso di uso
 471 tipico è quello in cui si salva un vettore (o un certo numero dei suoi
 472 elementi) con una chiamata del tipo:
 473 \begin{lstlisting}[labelstep=0,frame=,indent=1cm]{}
 474 int WriteVect(FILE * stream, double * vec, size_t nelem)
 475 {
 476     int size, nread;
 477     size = sizeof(*vec);
 478     if ( (nread = fwrite(vec, size, nelem, stream)) != nelem) {
 479         perror("Write error");
 480     }
 481     return nread;
 482 }
 483 \end{lstlisting}
 484 in questo caso devono essere specificate le dimensioni di ciascun
 485 elemento ed il numero di quelli che si vogliono scrivere. Un secondo
 486 caso è invece quello in cui si vuole trasferire su file una struttura;
 487 si avrà allora una chiamata tipo:
 488 \begin{lstlisting}[labelstep=0,frame=,indent=1cm]{}
 489 struct histogram {
 490     int nbins;
 491     double max, min;
 492     double * bin;
 493 } histo;
 494
 495 int WriteStruct(FILE * stream, struct histogram * histo, size_t nelem)
 496 {
 497     if ( fwrite(vec, sizeof(*histo), 1, stream) !=1) {
 498         perror("Write error");
 499     }
 500     return nread;
 501 }
 502 \end{lstlisting}
 503 in cui si specifica la dimensione dell'intera struttura ed un solo
 504 elemento.
 505
 506 In realtà quello che conta nel trasferimento dei dati sono le dimensioni
 507 totali, che sono sempre pari al prodotto \func{size * nelem}; la sola
 508 differenza è che le funzioni non ritornano il numero di byte scritti,
 509 ma il numero di elementi.
 510
 511 La funzione \func{fread} legge sempre un numero intero di elementi, se
 512 incontra la fine del file l'oggetto letto parzialmente viene scartato
 513 (lo stesso avviene in caso di errore). In questo caso la posizione dello
 514 stream viene settata alla fine del file (e non a quella corrispondente
 515 alla quantità di dati letti).
 516
 517 In caso di errore (o fine del file per \func{fread}) entrambe le
 518 funzioni restituiscono il numero di oggetti effettivamente letti o
 519 scritti, che sarà inferiore a quello richiesto. Contrariamente a quanto
 520 avviene per i file descriptor, questo segnala una condizione di errore e
 521 occorrerà usare \func{feof} e \func{ferror} per stabilire la natura del
 522 problema.
 523
 524 Benché queste funzioni assicurino la massima efficienza per il
 525 salvataggio dei dati, i dati memorizzati attraverso di esse presentano
 526 lo svantaggio di dipendere strettamente dalla piattaforma di sviluppo
 527 usata ed in genere possono essere riletti senza problemi solo dallo
 528 stesso programma che li ha prodotti.
 529
 530 Infatti diversi compilatori possono eseguire ottimizzazioni diverse
 531 delle strutture dati e alcuni compilatori (come il \cmd{gcc}) possono
 532 anche scegliere se ottimizzare l'occupazione di spazio, impacchettando
 533 più strettamente i dati, o la velocità inserendo opportuni
 534 \textit{padding} per l'allineamento dei medesimi generando quindi output
 535 binari diversi. Inoltre altre incompatibilità si possono presentare
 536 quando entrano in gioco differenze di architettura hardware, come la
 537 dimensione del bus o la modalità di ordinamento dei bit o il formato
 538 delle variabili in floating point.
 539
 540 Per questo motivo quando si usa l'input/output binario occorre sempre
 541 essere prendere le opportune precauzioni (in genere usare un formato di
 542 più alto livello che permetta di recuperare l'informazione completa),
 543 per assicurarsi che versioni diverse del programma siano in grado di
 544 rileggere i dati tenendo conto delle eventuali differenze.
 545
 546 Le \acr{glibc} definiscono altre due funzioni per l'I/O binario, che
 547 evitano il lock implicito dello stream, usato per dalla librerie per la
 548 gestione delle applicazioni multi-thread (si veda
 549 \secref{sec:file_stream_thread} per i dettagli).
 550
 551 \begin{functions}
 552   \headdecl{stdio.h}
 553
 554   \funcdecl{size\_t fread\_unlocked(void * ptr, size\_t size, size\_t
 555     nmemb, FILE * stream)}
 556
 557   \funcdecl{size\_t fwrite\_unlocked(const void * ptr, size\_t size,
 558     size\_t nmemb, FILE * stream)}
 559
 560   Le funzioni sono identiche alle analoghe \func{fread} e \func{fwrite}
 561   ma non acquisiscono il lock implicito sullo stream.
 562 \end{functions}
 563 \noindent entrambe le funzioni sono estensioni GNU previste solo dalle
 564 \acr{glibc}.
 565
 566
 567 \subsection{Input/output a caratteri}
 568 \label{sec:file_char_io}
 569
 570 La seconda modalità di input/output è quella a caratteri, in cui si
 571 trasferisce un carattere alla volta.
 572
 573 Le funzioni per la lettura a caratteri sono tre, \func{fgetc},
 574 \func{getc} e \func{getchar}, i rispettivi prototipi sono:
 575 \begin{functions}
 576   \headdecl{stdio.h}
 577
 578   \funcdecl{int getc(FILE *stream)} Legge un byte da \param{stream} e lo
 579   restituisce come intero. In genere è implementata come una macro.
 580
 581   \funcdecl{int fgetc(FILE *stream)} Legge un byte da \param{stream} e lo
 582   restituisce come intero. È una sempre una funzione.
 583
 584   \funcdecl{int getchar(void)} è equivalente a \func{getc(stdin)}.
 585
 586   Tutte queste funzioni leggono un byte alla volta, che viene restituito
 587   come intero; in caso di errore o fine del file il valore di ritorno è
 588   \macro{EOF}.
 589 \end{functions}
 590
 591 A parte \func{getchar}, che si usa in genere per leggere un carattere da
 592 tastiera, le altre due funzioni sono sostanzialmente equivalenti. La
 593 differenza è che \func{gets} è ottimizzata al massimo e normalmente
 594 viene implementata con una macro, per cui occorre stare attenti a cosa
 595 le si passa come argomento, infatti \param{stream} può essere valutato
 596 più volte nell'esecuzione, e non viene passato in copia con il
 597 meccanismo visto in \secref{sec:proc_var_passing}; per questo motivo se
 598 si passa una espressione si possono avere effetti indesiderati.
 599
 600 Invece \func{fgets} è assicurata essere sempre una funzione, per questo
 601 motivo la sua esecuzione normalmente è più lenta per via dell'overhead
 602 della chiamata, ma è altresì possibile ricavarne l'indirizzo, che può
 603 essere passato come parametro ad un altra funzione (e non si hanno i
 604 problemi accennati in precedenza con \param{stream}).
 605
 606 Le tre funzioni restituiscono tutte un \type{unsigned char} convertito
 607 ad \type{int} (si usa \type{unsigned char} in modo da evitare
 608 l'espansione del segno). In questo modo il valore di ritorno è sempre
 609 positivo, tranne in caso di errore o fine del file.
 610
 611 Nelle estenzioni GNU che provvedono la localizzazione sono definite tre
 612 funzioni equivalenti alle precedenti che invece di un carattere di un
 613 byte restituiscono un carattere in formato esteso (cioè di tipo
 614 \type{wint\_t}, il loro prototipo è:
 615 \begin{functions}
 616   \headdecl{stdio.h}
 617
 618   \funcdecl{wint\_t getwc(FILE *stream)} Legge un carattere esteso da
 619   \param{stream}. In genere è implementata come una macro.
 620
 621   \funcdecl{wint\_t fgetwc(FILE *stream)} Legge un carattere esteso da
 622   \param{stream} È una sempre una funzione.
 623
 624   \funcdecl{wint\_t getwchar(void)} è equivalente a \func{getwc(stdin)}.
 625
 626   Tutte queste funzioni leggono un carattere alla volta, in caso di
 627   errore o fine del file il valore di ritorno è \macro{WEOF}.
 628 \end{functions}
 629
 630 Per scrivere un carattere si possono usare tre funzioni analoghe alle
 631 precedenti usate per leggere: \func{putc}, \func{fputc} e
 632 \func{putchar}; i loro prototipi sono:
 633 \begin{functions}
 634   \headdecl{stdio.h}
 635
 636   \funcdecl{int putc(int c, FILE *stream)} Scrive il carattere \param{c}
 637   su \param{stream}. In genere è implementata come una macro.
 638
 639   \funcdecl{int fputc(FILE *stream)} Scrive il carattere \param{c} su
 640   \param{stream}. È una sempre una funzione.
 641
 642   \funcdecl{int putchar(void)} è equivalente a \func{putc(stdin)}.
 643
 644 \item \noindent Le funzioni scrivono sempre un carattere alla volta,
 645   il cui valore viene restituito in caso di successo; in caso di errore
 646   o fine del file il valore di ritorno è \macro{EOF}.
 647 \end{functions}
 648
 649 Tutte queste funzioni scrivono sempre un byte alla volta, anche se
 650 prendono come parametro un \type{int} (che pertanto deve essere ottenuto
 651 con un cast da un \type{unsigned char}). Anche il valore di ritorno è
 652 sempre un intero; in caso di errore o fine del file il valore di ritorno
 653 è \macro{EOF}.
 654
 655 Come nel caso dell'I/O binario le \acr{glibc} provvedono per ciascuna
 656 delle funzioni precedenti una seconda funzione, il cui nome è ottenuto
 657 aggiungendo un \func{\_unlocked}, che esegue esattamente le stesse
 658 operazioni evitando però il lock implicito dello stream.
 659
 660 Per compatibilità con SVID sono provviste anche due funzioni per leggere
 661 e scrivere una \textit{word} (che è sempre definita come \type{int}); i
 662 loro prototipi sono:
 663 \begin{functions}
 664   \headdecl{stdio.h}
 665
 666   \funcdecl{int getw(FILE *stream)} Legge una parola da \param{stream}.
 667   \funcdecl{int putw(int w, FILE *stream)} Scrive la parola \param{w} su
 668   \param{stream}.
 669
 670   Le funzioni restituiscono la parola \param{w}, o \macro{EOF} in caso
 671   di errore o di fine del file.
 672 \end{functions}
 673 l'uso di queste funzioni è deprecato in favore dell'uso di \func{fread}
 674 e \func{fwrite}, in quanto non è possibile distinguere il valore -1 da una
 675 condizione di errore che restituisce \macro{EOF}.
 676
 677
 678 \subsection{Input/output di linea}
 679 \label{sec:file_line_io}
 680
 681 La terza ed ultima modalità di input/output non formattato è quello di
 682 linea, in cui legge o scrive una riga alla volta; questa è una modalità
 683 molto usata, ma che presenta le caratteristiche più controverse.
 684
 685 Le funzioni per leggere una linea sono sostazialmente due, \func{gets} e
 686 \func{fgets}, i rispettivi prototipi sono:
 687 \begin{functions}
 688   \headdecl{stdio.h}
 689
 690   \funcdecl{char * gets(char * string)} Scrive su \param{string} una
 691   linea letta da \var{stdin}.
 692
 693   \funcdecl{char * fgets(char * string, int size, FILE *stream)}
 694   Scrive su \param{string} la linea letta da \param{stream} per un
 695   massimo di \param{size} byte.
 696
 697   Le funzioni restituiscono della stringa letta o \macro{NULL} in caso
 698   di errore.
 699 \end{functions}
 700
 701
 702
 703 \subsection{Input/output formattato}
 704 \label{sec:file_formatted_io}
 705
 706
 707 \subsection{Posizionamento su uno stream}
 708 \label{sec:file_fseek}
 709
 710
 711
 712 \section{Funzioni avanzate}
 713 \label{sec:file_stream_adv_func}
 714
 715 In questa sezione esamineremo le funzioni che permettono di controllare
 716 alcune caratteristiche più particolari degli stream, come la lettura
 717 degli attributi, le modalità di bufferizzazione, etc.
 718
 719
 720 \subsection{Le funzioni di controllo}
 721 \label{sec:file_stream_cntrl}
 722
 723 Al contrario di quanto avviene con i file descriptor le librerie standard del
 724 C non prevedono nessuna funzione come la \func{fcntl} per la lettura degli
 725 attributi degli stream; le \acr{glibc} però supportano alcune estensioni
 726 derivate da Solaris, che permettono di ottenere informazioni utili.
 727
 728 In certi casi può essere necessario sapere se un certo stream è accessibile in
 729 lettura o scrittura. In genere questa informazione non è disponibile, e si
 730 deve ricordare come il file è stato aperto. La cosa può essere complessa se le
 731 operazioni vengono effettuate in una subroutine, che a questo punto
 732 necessiterà di informazioni aggiuntive rispetto al semplice puntatore allo
 733 stream; questo può essere evitato con le due funzioni \func{\_\_freadable} e
 734 \func{\_\_fwritable} i cui prototipi sono:
 735 \begin{functions}
 736   \headdecl{stdio\_ext.h}
 737   \funcdecl{int \_\_freadable (FILE * stream)}
 738   Restituisce un valore diverso da zero se \param{stream} consente la lettura.
 739
 740   \funcdecl{int \_\_fwritable(FILE * stream)}
 741   Restituisce un valore diverso da zero se \param{stream} consente la
 742   scrittura.
 743 \end{functions}
 744
 745 Altre due funzioni, \func{\_\_freading} e \func{\_\_fwriting} servono ad un
 746 uso ancora più specialistico, il loro prototipo è:
 747 \begin{functions}
 748   \headdecl{stdio\_ext.h}
 749   \funcdecl{int \_\_freading (FILE * stream)}
 750   Restituisce un valore diverso da zero se \param{stream} è aperto in sola
 751   lettura o se l'ultima operazione è stata di lettura.
 752
 753   \funcdecl{int \_\_fwriting(FILE * stream)}
 754   Restituisce un valore diverso da zero se \param{stream} è aperto in sola
 755   scrittura o se l'ultima operazione è stata di scrittura.
 756 \end{functions}
 757
 758 Le due funzioni hanno lo scopo di determinare di che tipo è stata l'ultima
 759 operazione eseguita su uno stream aperto in lettura/scrittura; ovviamente se
 760 uno stream è aperto in sola lettura (o sola scrittura) la modalità dell'ultima
 761 operazione è sempre determinata; l'unica ambiguità è quando non sono state
 762 ancora eseguite operazioni, in questo caso le funzioni rispondono come se
 763 una operazione ci fosse comunque stata.
 764
 765 La conoscenza dell'ultima operazione effettuata su uno stream aperto in
 766 lettura/scrittura è utile in quanto permette di trarre conclusioni sullo stato
 767 del buffer e del suo contenuto.
 768
 769
 770 \subsection{Il controllo della bufferizzazione}
 771 \label{sec:file_buffering_ctrl}
 772
 773 Come accennato in \secref{sec:file_buffering} le librerie definiscono una
 774 serie di funzioni che permettono di controllare il comportamento degli
 775 stream; se non si è
 776
 777
 778 \subsection{Gli stream e i thread}
 779 \label{sec:file_stream_thread}
 780
 781 Gli stream possono essere usati in applicazioni multi-thread allo stesso
 782 modo in cui sono usati nelle applicazioni normali, ma si deve essere
 783 consapovoli delle possibili complicazioni anche quando non si usano i
 784 thread, dato che l'implementazione delle librerie è influenzata
 785 pesantemente dalle richieste necessarie per garantirne l'uso coi thread.
 786
 787
 788
 789 \begin{functions}
 790   \headdecl{stdio.h}
 791
 792   \funcdecl{void flockfile(FILE * stream)} Esegue l'acquisizione del
 793   lock dello stream \param{stream}, bloccandosi in caso il lock non
 794   disponibile.
 795
 796   \funcdecl{int ftrylockfile(FILE * stream)} Tenta l'acquisizione del
 797   lock dello stream \param{stream}, senza bloccarsi in caso il lock non sia
 798   disponibile. Ritorna zero in caso di acquisizione del lock, diverso da
 799   zero altrimenti.
 800
 801   \funcdecl{void funlockfile(FILE * stream)} Rilascia il lock dello
 802   stream \param{stream}.
 803 \end{functions}
 804
 805
 806 \subsection{Dettagli dell'implementazione}
 807 \label{sec:file_stream_details}
 808
 809
 810 \subsection{File temporanei}
 811 \label{sec:file_temp_file}
 812
 813
 814 \subsection{Efficienza}
 815 \label{sec:file_stream_efficiency}
 816