c8936db9b51950b41b290fd982215f245d171725
[gapil.git] / 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{cap: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 permettono di aprire uno stream sono tre\footnote{\func{fopen}
213   e \func{freopen} fanno parte dello standard ANSI C, \func{fdopen} è parte
214 dello standard POSIX.1.}, i loro prototipi sono:
215 \begin{functions}
216   \headdecl{stdio.h}
217   \funcdecl{FILE * fopen(const char * path, const char *mode)}
218   Apre il file specificato da \param{path}.
219   \funcdecl{FILE * fdopen(int fildes, const char * mode)}
220   Associa uno stream al file descriptor \param{fildes}.
221   \funcdecl{FILE * freopen(const char * path, const char * mode, FILE *
222   stream)}
223   Apre il file specificato da \param{path} associandolo allo stream
224   specificato da \param{stream}, se questo è già aperto prima lo chiude.
225
226   Le funzioni ritornano un puntatore valido in caso di successo e \macro{NULL}
227   in caso di errore, in tal caso \var{errno} viene settata al valore ricevuto
228   dalla funzione sottostante di cui è fallita l'esecuzione.
229   
230   Gli errori pertanto possono essere quelli di \func{malloc} per tutte e tre
231   le funzioni, quelli \func{open} per \func{fopen}, quelli di \func{fcntl} per
232   \func{fdopen} e quelli di \func{fopen}, \func{fclose} e \func{fflush} per
233   \func{freopen}. 
234 \end{functions}
235
236 Normalmente la funzione che si usa per aprire uno stream è \func{fopen},
237 essa apre il file specificato nella modalità specificata da
238 \param{mode}, che è una stringa che deve iniziare con almeno uno dei
239 valori indicati in \tabref{tab:file_fopen_mode} (sono possibili varie
240 estensioni che vedremo in seguito).
241
242 L'uso più comune di \func{freopen} è per redirigere uno dei tre file
243 standard (vedi \secref{sec:file_std_stream}): il file \param{path} viene
244 associato a \param{stream} e se questo è uno stream già aperto viene
245 preventivamente chiuso.
246
247 Infine \func{fdopen} viene usata per associare uno stream ad un file
248 descriptor esistente ottenuto tramite una altra funzione (ad esempio con
249 una \func{open}, una \func{dup}, o una \func{pipe}) e serve quando si
250 vogliono usare gli stream con file come le fifo o i socket, che non
251 possono essere aperti con le funzioni delle librerie standard del C.
252
253 \begin{table}[htb]
254   \centering
255   \begin{tabular}[c]{|l|p{8cm}|}
256     \hline
257     \textbf{Valore} & \textbf{Significato}\\
258     \hline
259     \hline
260     \texttt{r} & Il file viene aperto, l'accesso viene posto in sola
261     lettura, lo stream è posizionato all'inizio del file.\\
262     \texttt{r+} & Il file viene aperto, l'accesso viene posto in lettura e
263     scrittura, lo stream è posizionato all'inizio del file. \\
264 %    \hline
265     \texttt{w} & Il file viene aperto e troncato a lunghezza nulla (o
266     creato se non esiste), l'accesso viene posto in sola scrittura, lo
267     stream è posizionato all'inizio del file.\\
268     \texttt{w+} & Il file viene aperto e troncato a lunghezza nulla (o
269     creato se non esiste), l'accesso viene posto in scrittura e lettura,
270     lo stream è posizionato all'inizio del file.\\
271 %    \hline
272     \texttt{a} & Il file viene aperto (o creato se non esiste) in
273     \textit{append mode}, l'accesso viene posto in sola scrittura. \\
274     \texttt{a+} & Il file viene aperto (o creato se non esiste) in
275     \textit{append mode}, l'accesso viene posto in lettura e scrittura. \\
276     \hline
277   \end{tabular}
278   \caption{Modalità di apertura di uno stream dello standard ANSI C che
279     sono sempre presenti in qualunque sistema POSIX}
280   \label{tab:file_fopen_mode}
281 \end{table}
282
283 In realtà lo standard ANSI C prevede un totale di 15 possibili valori
284 diversi per \param{mode}, ma in \tabref{tab:file_fopen_mode} si sono
285 riportati solo i sei valori effettivi, ad essi può essere aggiunto pure
286 il carattere \func{b} (come ultimo carattere o nel mezzo agli altri per
287 le stringhe di due caratteri) che in altri sistemi operativi serve a
288 distinguere i file binari dai file di testo; in un sistema POSIX questa
289 distinzione non esiste e il valore viene accettato solo per
290 compatibilità, ma non ha alcun effetto.
291
292 Le \acr{glibc} supportano alcune estensioni, queste devono essere sempre
293 indicate dopo aver specificato il \param{mode} con uno dei valori di
294 \tabref{tab:file_fopen_mode}. L'uso del carattere \texttt{x} serve per
295 evitare di sovrascrivere un file già esistente (è analoga all'uso
296 dell'opzione \macro{O\_EXCL} in \func{open}), se il file specificato già
297 esiste e si aggiunge questo carattere a \param{mode} la \func{fopen}
298 fallisce. 
299
300 Un'altra estensione serve a supportare la localizzazione, quando si
301 aggiunge a \param{mode} una stringa della forma \verb|",ccs=STRING"| il
302 valore \verb|STRING| è considerato il nome di una codifica dei caratteri
303 e \func{fopen} marca il file per l'uso dei caratteri estesi e abilita le
304 opportune funzioni di conversione in lettura e scrittura.
305
306 Inoltre nel caso si usi \func{fdopen} i valori specificati da
307 \param{mode} devono essere compatibili con quelli con cui il file
308 descriptor è stato aperto. Inoltre i modi \cmd{w} e \cmd{w+} non
309 troncano il file. La posizione nello stream viene settata a quella
310 corrente nel file descriptor, e le variabili di errore e di fine del
311 file (vedi \secref{sec:file_io}) sono cancellate. Il file non viene
312 duplicato e verrà chiuso alla chiusura dello stream.
313
314 I nuovi file saranno creati secondo quanto visto in
315 \secref{sec:file_ownership} ed avranno i permessi di accesso settati al
316 valore \macro{S\_IRUSR|S\_IWUSR|S\_IRGRP|S\_IWGRP|S\_IROTH|S\_IWOTH}
317 (pari a \macro{0666}) modificato secondo il valore di \acr{umask} per il
318 processo (si veda \secref{sec:file_umask}).
319
320 In caso di file aperti in lettura e scrittura occorre ricordarsi che c'è
321 di messo una bufferizzazione; per questo motivo lo standard ANSI C
322 richiede che ci sia una operazione di posizionamento fra una operazione
323 di output ed una di input o viceversa (eccetto il caso in cui l'input ha
324 incontrato la fine del file), altrimenti una lettura può ritornare anche
325 il risultato di scritture precedenti l'ultima effettuata. 
326
327 Per questo motivo è una buona pratica (e talvolta necessario) far seguire ad
328 una scrittura una delle funzioni \func{fflush}, \func{fseek}, \func{fsetpos} o
329 \func{rewind} prima di eseguire una rilettura; viceversa nel caso in cui si
330 voglia fare una scrittura subito dopo aver eseguito una lettura occorre prima
331 usare una delle funzioni \func{fseek}, \func{fsetpos} o \func{rewind}. Anche
332 una operazione nominalmente nulla come \func{fseek(file, 0, SEEK\_CUR)} è
333 sufficiente a garantire la sincronizzazione.
334
335 Una volta aperto lo stream, si può cambiare la modalità di bufferizzazione
336 (vedi \secref{sec:file_buffering_ctrl}) fintanto che non si è effettuato
337 alcuna operazione di I/O sul file.
338
339 Uno stream viene chiuso con la funzione \func{fclose} il cui prototipo è:
340 \begin{prototype}{stdio.h}{int fclose(FILE * stream)}
341   Chiude lo stream \param{stream}. 
342   
343   Restituisce 0 in caso di successo e \macro{EOF} in caso di errore, nel qual
344   caso setta \var{errno} a \macro{EBADF} se il file descriptor indicato da
345   \param{stream} non è valido, o uno dei valori specificati dalla sottostante
346   funzione che è fallita (\func{close}, \func{write} o \func{fflush}).
347 \end{prototype}
348
349 La funzione effettua uno scarico di tutti i dati presenti nei buffer di
350 uscita e scarta tutti i dati in ingresso, se era stato allocato un
351 buffer per lo stream questo verrà rilasciato. La funzione effettua lo
352 scarico solo per i dati presenti nei buffer in user space usati dalle
353 \acr{glibc}; se si vuole essere sicuri che il kernel forzi la scrittura
354 su disco occorrerà effettuare una \func{sync}.
355
356 Linux supporta, come estensione implementata dalle \acr{glibc}, anche una
357 altra funzione, \func{fcloseall}, che serve a chiudere tutti i file, il suo
358 prototipo è:
359 \begin{prototype}{stdio.h}{int fcloseall(void)}
360   Chiude tutti gli stream. 
361   
362   Restituisce 0 se non ci sono errori ed \macro{EOF} altrimenti.
363 \end{prototype}
364 la funzione esegue lo scarico dei dati bufferizzati in uscita e scarta quelli
365 in ingresso, chiudendo tutti i file. Questa funzione è provvista solo per i
366 casi di emergenza, quando si è verificato un errore ed il programma deve
367 essere abortito, ma si vuole compiere qualche altra operazione dopo aver
368 chiuso i file e prima di uscire (si ricordi quanto visto in
369 \secref{sec:proc_exit}).
370
371
372 \subsection{Lettura e scrittura su uno stream}
373 \label{sec:file_io}
374
375 Una delle caratteristiche più utili dell'interfaccia degli stream è la
376 ricchezza delle funzioni disponibili per le operazioni di lettura e
377 scrittura sui file. Sono infatti previste ben tre diverse modalità
378 modalità di input/output non formattato:
379 \begin{enumerate*}
380 \item\textsl{binario} in cui legge/scrive un blocco di dati alla
381   volta, vedi \secref{sec:file_binary_io}.
382 \item\textsl{di linea} in cui si legge/scrive una linea (terminata dal
383   carattere di newline \verb|\n|) alla volta, vedi
384   \secref{sec:file_line_io}.
385 \item\textsl{a caratteri} in cui si legge/scrive un carattere alla
386   volta (con la bufferizzazione gestita automaticamente dalla libreria),
387   vedi \secref{sec:file_char_io}.
388 \end{enumerate*}
389 ed inoltre la modalità di input/output formattato.
390
391 A differenza dell'interfaccia dei file descriptor, con gli stream il
392 raggiungimento della fine del file è considerato un errore, e viene
393 notificato come tale dai valori di uscita delle varie funzioni. Nella
394 maggior parte dei casi questo avviene con la restituzione del valore
395 intero (di tipo \type{int}) \macro{EOF}\footnote{la costante deve essere
396   negativa, le \acr{glibc} usano -1, altre implementazioni possono avere
397   valori diversi.}  definito anch'esso nell'header \func{stdlib.h}.
398
399 Dato che le funzioni dell'interfaccia degli stream sono funzioni di libreria
400 che si appoggiano a delle system call, esse non settano direttamente la
401 variabile \var{errno}, che mantiene il valore settato dalla system call che ha
402 riportato l'errore. 
403
404 Siccome la condizione di end-of-file è anch'essa segnalata come errore, nasce
405 il problema di come distinguerla da un errore effettivo; basarsi solo sul
406 valore di ritorno della funzione e controllare il valore di \var{errno}
407 infatti non basta, dato che quest'ultimo potrebbe essere stato settato in una
408 altra occasione, (si veda \secref{sec:sys_errno} per i dettagli del
409 funzionamento di \var{errno}).
410
411 Per questo motivo tutte le implementazioni delle librerie standard
412 mantengono per ogni stream almeno due flag all'interno dell'oggetto
413 \type{FILE}, il flag di \textit{end-of-file}, che segnala che si è
414 raggiunta la fine del file in lettura, e quello di errore, che segnala
415 la presenza di un qualche errore nelle operazioni di input/output;
416 questi due flag possono essere riletti dalle funzioni:
417 \begin{functions}
418   \headdecl{stdio.h}
419   \funcdecl{int feof(FILE *stream)}
420   Controlla il flag di end-of-file di \param{stream}.
421   \funcdecl{int ferror(FILE *stream)}
422   Controlla il flag di errore di \param{stream}.
423
424   Entrambe le funzioni ritornano un valore diverso da zero se i relativi
425   flag sono settati. 
426 \end{functions}
427 \noindent si tenga presente comunque che la lettura di questi flag segnala
428 soltanto che c'è stato un errore, o che si è raggiunta la fine del file in una
429 qualunque operazione sullo stream, il controllo quindi deve essere effettuato
430 ogni volta che si chiama una funzione di libreria.
431
432 Entrambi i flag (di errore e di end-of-file) possono essere cancellati usando
433 la funzione \func{clearerr}, il cui prototipo è:
434 \begin{prototype}{stdio.h}{void clearerr( FILE *stream)}
435   Cancella i flag di errore ed end-of-file di \param{stream}. 
436 \end{prototype}
437 \noindent in genere si usa questa funziona una volta che si sia identificata e
438 corretta la causa di un errore per evitare di mantenere i flag attivi,
439 così da poter rilevare una successiva ulteriore condizione di errore.
440
441
442 \subsection{Input/output binario}
443 \label{sec:file_binary_io}
444
445 La prima modalità di input/output non formattato ricalca quella della
446 interfaccia dei file descriptor, e provvede semplicemente la scrittura e
447 la lettura dei dati da un buffer verso un file e viceversa. In generale
448 questa è la modalità che si usa quando si ha a che fare con dati non
449 formattati. Le due funzioni che si usano per l'I/O binario sono:
450 \begin{functions}
451   \headdecl{stdio.h} 
452   \funcdecl{size\_t fread(void * ptr, size\_t size,
453     size\_t nmemb, FILE * stream)} 
454   \funcdecl{size\_t fwrite(const void *
455     ptr, size\_t size, size\_t nmemb, FILE * stream)}
456   
457   Le funzioni rispettivamente leggono e scrivono \param{nmemb} elementi
458   di dimensione \param{size} dal buffer \param{ptr} al file \param{stream}.
459   
460   Entrambe le funzioni ritornano il numero di elementi letti o scritti,
461   in caso di errore o fine del file viene restituito un numero di
462   elementi inferiore al richiesto.
463 \end{functions}
464
465 In genere si usano queste funzioni quando si devono trasferire su file
466 blocchi di dati binari in maniera compatta e veloce; un primo caso di uso
467 tipico è quello in cui si salva un vettore (o un certo numero dei suoi
468 elementi) con una chiamata del tipo:
469 \begin{lstlisting}[labelstep=0,frame=,indent=1cm]{}
470 int WriteVect(FILE * stream, double * vec, size_t nelem) 
471 {
472     int size, nread;
473     size = sizeof(*vec);
474     if ( (nread = fwrite(vec, size, nelem, stream)) != nelem) {
475         perror("Write error");
476     }
477     return nread;
478 }
479 \end{lstlisting}
480 in questo caso devono essere specificate le dimensioni di ciascun
481 elemento ed il numero di quelli che si vogliono scrivere. Un secondo
482 caso è invece quello in cui si vuole trasferire su file una struttura;
483 si avrà allora una chiamata tipo:
484 \begin{lstlisting}[labelstep=0,frame=,indent=1cm]{}
485 struct histogram {
486     int nbins; 
487     double max, min;
488     double * bin;
489 } histo; 
490
491 int WriteStruct(FILE * stream, struct histogram * histo, size_t nelem) 
492 {
493     if ( fwrite(vec, sizeof(*histo), 1, stream) !=1) {
494         perror("Write error");
495     }
496     return nread;
497 }
498 \end{lstlisting}
499 in cui si specifica la dimensione dell'intera struttura ed un solo
500 elemento. 
501
502 In realtà quello che conta nel trasferimento dei dati sono le dimensioni
503 totali, che sono sempre pari al prodotto \func{size * nelem}; la sola
504 differenza è che le funzioni non ritornano il numero di byte scritti,
505 ma il numero di elementi.
506
507 La funzione \func{fread} legge sempre un numero intero di elementi, se
508 incontra la fine del file l'oggetto letto parzialmente viene scartato
509 (lo stesso avviene in caso di errore). In questo caso la posizione dello
510 stream viene settata alla fine del file (e non a quella corrispondente
511 alla quantità di dati letti).
512
513 In caso di errore (o fine del file per \func{fread}) entrambe le
514 funzioni restituiscono il numero di oggetti effettivamente letti o
515 scritti, che sarà inferiore a quello richiesto. Contrariamente a quanto
516 avviene per i file descriptor, questo segnala una condizione di errore e
517 occorrerà usare \func{feof} e \func{ferror} per stabilire la natura del
518 problema.
519
520 Benché queste funzioni assicurino la massima efficienza per il
521 salvataggio dei dati, i dati memorizzati attraverso di esse presentano
522 lo svantaggio di dipendere strettamente dalla piattaforma di sviluppo
523 usata ed in genere possono essere riletti senza problemi solo dallo
524 stesso programma che li ha prodotti.
525
526 Infatti diversi compilatori possono eseguire ottimizzazioni diverse
527 delle strutture dati e alcuni compilatori (come il \cmd{gcc}) possono
528 anche scegliere se ottimizzare l'occupazione di spazio, impacchettando
529 più strettamente i dati, o la velocità inserendo opportuni
530 \textit{padding} per l'allineamento dei medesimi generando quindi output
531 binari diversi. Inoltre altre incompatibilità si possono presentare
532 quando entrano in gioco differenze di architettura hardware, come la
533 dimensione del bus o la modalità di ordinamento dei bit o il formato
534 delle variabili in floating point.
535
536 Per questo motivo quando si usa l'input/output binario occorre sempre
537 essere prendere le opportune precauzioni (in genere usare un formato di
538 più alto livello che permetta di recuperare l'informazione completa),
539 per assicurarsi che versioni diverse del programma siano in grado di
540 rileggere i dati tenendo conto delle eventuali differenze.
541
542 Le \acr{glibc} definiscono altre due funzioni per l'I/O binario, che
543 evitano il lock implicito dello stream, usato per dalla librerie per la
544 gestione delle applicazioni multi-thread (si veda
545 \secref{sec:file_stream_thread} per i dettagli).
546
547 \begin{functions}
548   \headdecl{stdio.h} 
549   
550   \funcdecl{size\_t fread\_unlocked(void * ptr, size\_t size, size\_t
551     nmemb, FILE * stream)}
552   
553   \funcdecl{size\_t fwrite\_unlocked(const void * ptr, size\_t size,
554     size\_t nmemb, FILE * stream)}
555   
556   Le funzioni sono identiche alle analoghe \func{fread} e \func{fwrite}
557   ma non acquisiscono il lock implicito sullo stream.
558 \end{functions}
559 \noindent entrambe le funzioni sono estensioni GNU previste solo dalle
560   \acr{glibc}. 
561
562
563 \subsection{Input/output a caratteri singoli}
564 \label{sec:file_char_io}
565
566
567
568
569 \subsection{Input/output di linea}
570 \label{sec:file_line_io}
571
572
573 \subsection{Input/output formattato}
574 \label{sec:file_formatted_io}
575
576
577 \subsection{Posizionamento su uno stream}
578 \label{sec:file_fseek}
579
580
581
582 \section{Funzioni avanzate}
583 \label{sec:file_stream_adv_func}
584
585 In questa sezione esamineremo le funzioni che permettono di controllare
586 alcune caratteristiche più particolari degli stream, come la lettura
587 degli attributi, le modalità di bufferizzazione, etc.
588
589
590 \subsection{Le funzioni di controllo}
591 \label{sec:file_stream_cntrl}
592
593 Al contrario di quanto avviene con i file descriptor le librerie standard del
594 C non prevedono nessuna funzione come la \func{fcntl} per la lettura degli
595 attributi degli stream; le \acr{glibc} però supportano alcune estensioni
596 derivate da Solaris, che permettono di ottenere informazioni utili.
597
598 In certi casi può essere necessario sapere se un certo stream è accessibile in
599 lettura o scrittura. In genere questa informazione non è disponibile, e si
600 deve ricordare come il file è stato aperto. La cosa può essere complessa se le
601 operazioni vengono effettuate in una subroutine, che a questo punto
602 necessiterà di informazioni aggiuntive rispetto al semplice puntatore allo
603 stream; questo può essere evitato con le due funzioni \func{\_\_freadable} e
604 \func{\_\_fwritable} i cui prototipi sono:
605 \begin{functions}
606   \headdecl{stdio\_ext.h}
607   \funcdecl{int \_\_freadable (FILE * stream)}
608   Restituisce un valore diverso da zero se \param{stream} consente la lettura.
609
610   \funcdecl{int \_\_fwritable(FILE * stream)}  
611   Restituisce un valore diverso da zero se \param{stream} consente la
612   scrittura.
613 \end{functions}
614
615 Altre due funzioni, \func{\_\_freading} e \func{\_\_fwriting} servono ad un
616 uso ancora più specialistico, il loro prototipo è: 
617 \begin{functions}
618   \headdecl{stdio\_ext.h}
619   \funcdecl{int \_\_freading (FILE * stream)}
620   Restituisce un valore diverso da zero se \param{stream} è aperto in sola
621   lettura o se l'ultima operazione è stata di lettura.
622
623   \funcdecl{int \_\_fwriting(FILE * stream)}  
624   Restituisce un valore diverso da zero se \param{stream} è aperto in sola
625   scrittura o se l'ultima operazione è stata di scrittura.
626 \end{functions}
627
628 Le due funzioni hanno lo scopo di determinare di che tipo è stata l'ultima
629 operazione eseguita su uno stream aperto in lettura/scrittura; ovviamente se
630 uno stream è aperto in sola lettura (o sola scrittura) la modalità dell'ultima
631 operazione è sempre determinata; l'unica ambiguità è quando non sono state
632 ancora eseguite operazioni, in questo caso le funzioni rispondono come se
633 una operazione ci fosse comunque stata.
634
635 La conoscenza dell'ultima operazione effettuata su uno stream aperto in
636 lettura/scrittura è utile in quanto permette di trarre conclusioni sullo stato
637 del buffer e del suo contenuto.
638
639
640 \subsection{Il controllo della bufferizzazione}
641 \label{sec:file_buffering_ctrl}
642
643 Come accennato in \secref{sec:file_buffering} le librerie definiscono una
644 serie di funzioni che permettono di controllare il comportamento degli
645 stream; se non si è 
646
647
648 \subsection{Gli stream e i thread}
649 \label{sec:file_stream_thread}
650
651 Gli stream possono essere usati in applicazioni multi-thread allo stesso
652 modo in cui sono usati nelle applicazioni normali, ma si deve essere
653 consapovoli delle possibili complicazioni anche quando non si usano i
654 thread, dato che l'implementazione delle librerie è influenzata
655 pesantemente dalle richieste necessarie per garantirne l'uso coi thread.
656
657
658
659 \begin{functions}
660   \headdecl{stdio.h}
661   
662   \funcdecl{void flockfile(FILE * stream)} Esegue l'acquisizione del
663   lock dello stream \param{stream}, bloccandosi in caso il lock non
664   disponibile. 
665   
666   \funcdecl{int ftrylockfile(FILE * stream)} Tenta l'acquisizione del
667   lock dello stream \param{stream}, senza bloccarsi in caso il lock non sia
668   disponibile. Ritorna zero in caso di acquisizione del lock, diverso da
669   zero altrimenti.
670   
671   \funcdecl{void funlockfile(FILE * stream)} Rilascia il lock dello
672   stream \param{stream}.
673 \end{functions}
674
675
676 \subsection{Dettagli dell'implementazione}
677 \label{sec:file_stream_details}
678
679
680 \subsection{File temporanei}
681 \label{sec:file_temp_file}
682
683
684 \subsection{Efficienza}
685 \label{sec:file_stream_efficiency}
686