1 \chapter{I file: l'interfaccia standard ANSI C}
2 \label{cha:files_std_interface}
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.
11 \section{Introduzione}
12 \label{sec:file_stream_intro}
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.
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}.
26 \subsection{I \textit{file stream}}
27 \label{sec:file_stream}
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.
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
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.
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.
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.
63 \subsection{Gli oggetti \type{FILE}}
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.
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
82 \subsection{Gli stream standard}
83 \label{sec:file_std_stream}
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:
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
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
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]{}
111 stdout = fopen ("standard-output-file", "w");
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}.
118 \subsection{Le modalità di bufferizzazione}
119 \label{sec:file_buffering}
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.
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.
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.
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:
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
158 \item \textit{fully buffered}: in questo caso i caratteri vengono
159 trasmessi da e verso il file in blocchi di dimensione opportuna.
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}.
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}
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.
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}.
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.
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
200 \section{Funzioni base}
201 \label{sec:file_ansi_base_func}
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.
209 \subsection{Apertura e chiusura di uno stream}
210 \label{sec:file_fopen}
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
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 *
224 Apre il file specificato da \param{path} associandolo allo stream
225 specificato da \param{stream}, se questo è già aperto prima lo chiude.
227 \bodydesc{Le funzioni ritornano un puntatore valido in caso di
228 successo e \macro{NULL} in caso di errore, in tal caso \var{errno}
229 viene settata al valore ricevuto dalla funzione sottostante di cui è
230 fallita l'esecuzione.
232 Gli errori pertanto possono essere quelli di \func{malloc} per tutte
233 e tre le funzioni, quelli \func{open} per \func{fopen}, quelli di
234 \func{fcntl} per \func{fdopen} e quelli di \func{fopen},
235 \func{fclose} e \func{fflush} per \func{freopen}.}
238 Normalmente la funzione che si usa per aprire uno stream è \func{fopen},
239 essa apre il file specificato nella modalità specificata da
240 \param{mode}, che è una stringa che deve iniziare con almeno uno dei
241 valori indicati in \tabref{tab:file_fopen_mode} (sono possibili varie
242 estensioni che vedremo in seguito).
244 L'uso più comune di \func{freopen} è per redirigere uno dei tre file
245 standard (vedi \secref{sec:file_std_stream}): il file \param{path} viene
246 associato a \param{stream} e se questo è uno stream già aperto viene
247 preventivamente chiuso.
249 Infine \func{fdopen} viene usata per associare uno stream ad un file
250 descriptor esistente ottenuto tramite una altra funzione (ad esempio con
251 una \func{open}, una \func{dup}, o una \func{pipe}) e serve quando si
252 vogliono usare gli stream con file come le fifo o i socket, che non
253 possono essere aperti con le funzioni delle librerie standard del C.
257 \begin{tabular}[c]{|l|p{8cm}|}
259 \textbf{Valore} & \textbf{Significato}\\
262 \texttt{r} & Il file viene aperto, l'accesso viene posto in sola
263 lettura, lo stream è posizionato all'inizio del file.\\
264 \texttt{r+} & Il file viene aperto, l'accesso viene posto in lettura e
265 scrittura, lo stream è posizionato all'inizio del file. \\
267 \texttt{w} & Il file viene aperto e troncato a lunghezza nulla (o
268 creato se non esiste), l'accesso viene posto in sola scrittura, lo
269 stream è posizionato all'inizio del file.\\
270 \texttt{w+} & Il file viene aperto e troncato a lunghezza nulla (o
271 creato se non esiste), l'accesso viene posto in scrittura e lettura,
272 lo stream è posizionato all'inizio del file.\\
274 \texttt{a} & Il file viene aperto (o creato se non esiste) in
275 \textit{append mode}, l'accesso viene posto in sola scrittura. \\
276 \texttt{a+} & Il file viene aperto (o creato se non esiste) in
277 \textit{append mode}, l'accesso viene posto in lettura e scrittura. \\
280 \caption{Modalità di apertura di uno stream dello standard ANSI C che
281 sono sempre presenti in qualunque sistema POSIX}
282 \label{tab:file_fopen_mode}
285 In realtà lo standard ANSI C prevede un totale di 15 possibili valori
286 diversi per \param{mode}, ma in \tabref{tab:file_fopen_mode} si sono
287 riportati solo i sei valori effettivi, ad essi può essere aggiunto pure
288 il carattere \func{b} (come ultimo carattere o nel mezzo agli altri per
289 le stringhe di due caratteri) che in altri sistemi operativi serve a
290 distinguere i file binari dai file di testo; in un sistema POSIX questa
291 distinzione non esiste e il valore viene accettato solo per
292 compatibilità, ma non ha alcun effetto.
294 Le \acr{glibc} supportano alcune estensioni, queste devono essere sempre
295 indicate dopo aver specificato il \param{mode} con uno dei valori di
296 \tabref{tab:file_fopen_mode}. L'uso del carattere \texttt{x} serve per
297 evitare di sovrascrivere un file già esistente (è analoga all'uso
298 dell'opzione \macro{O\_EXCL} in \func{open}), se il file specificato già
299 esiste e si aggiunge questo carattere a \param{mode} la \func{fopen}
302 Un'altra estensione serve a supportare la localizzazione, quando si
303 aggiunge a \param{mode} una stringa della forma \verb|",ccs=STRING"| il
304 valore \verb|STRING| è considerato il nome di una codifica dei caratteri
305 e \func{fopen} marca il file per l'uso dei caratteri estesi e abilita le
306 opportune funzioni di conversione in lettura e scrittura.
308 Inoltre nel caso si usi \func{fdopen} i valori specificati da
309 \param{mode} devono essere compatibili con quelli con cui il file
310 descriptor è stato aperto. Inoltre i modi \cmd{w} e \cmd{w+} non
311 troncano il file. La posizione nello stream viene settata a quella
312 corrente nel file descriptor, e le variabili di errore e di fine del
313 file (vedi \secref{sec:file_io}) sono cancellate. Il file non viene
314 duplicato e verrà chiuso alla chiusura dello stream.
316 I nuovi file saranno creati secondo quanto visto in
317 \secref{sec:file_ownership} ed avranno i permessi di accesso settati al
318 valore \macro{S\_IRUSR|S\_IWUSR|S\_IRGRP|S\_IWGRP|S\_IROTH|S\_IWOTH}
319 (pari a \macro{0666}) modificato secondo il valore di \acr{umask} per il
320 processo (si veda \secref{sec:file_umask}).
322 In caso di file aperti in lettura e scrittura occorre ricordarsi che c'è
323 di messo una bufferizzazione; per questo motivo lo standard ANSI C
324 richiede che ci sia una operazione di posizionamento fra una operazione
325 di output ed una di input o viceversa (eccetto il caso in cui l'input ha
326 incontrato la fine del file), altrimenti una lettura può ritornare anche
327 il risultato di scritture precedenti l'ultima effettuata.
329 Per questo motivo è una buona pratica (e talvolta necessario) far seguire ad
330 una scrittura una delle funzioni \func{fflush}, \func{fseek}, \func{fsetpos} o
331 \func{rewind} prima di eseguire una rilettura; viceversa nel caso in cui si
332 voglia fare una scrittura subito dopo aver eseguito una lettura occorre prima
333 usare una delle funzioni \func{fseek}, \func{fsetpos} o \func{rewind}. Anche
334 una operazione nominalmente nulla come \func{fseek(file, 0, SEEK\_CUR)} è
335 sufficiente a garantire la sincronizzazione.
337 Una volta aperto lo stream, si può cambiare la modalità di bufferizzazione
338 (vedi \secref{sec:file_buffering_ctrl}) fintanto che non si è effettuato
339 alcuna operazione di I/O sul file.
341 Uno stream viene chiuso con la funzione \func{fclose} il cui prototipo è:
342 \begin{prototype}{stdio.h}{int fclose(FILE * stream)}
343 Chiude lo stream \param{stream}.
345 \bodydesc{Restituisce 0 in caso di successo e \macro{EOF} in caso di errore,
346 nel qual caso setta \var{errno} a \macro{EBADF} se il file descriptor
347 indicato da \param{stream} non è valido, o uno dei valori specificati
348 dalla sottostante funzione che è fallita (\func{close}, \func{write} o
352 La funzione effettua uno scarico di tutti i dati presenti nei buffer di
353 uscita e scarta tutti i dati in ingresso, se era stato allocato un
354 buffer per lo stream questo verrà rilasciato. La funzione effettua lo
355 scarico solo per i dati presenti nei buffer in user space usati dalle
356 \acr{glibc}; se si vuole essere sicuri che il kernel forzi la scrittura
357 su disco occorrerà effettuare una \func{sync}.
359 Linux supporta, come estensione implementata dalle \acr{glibc}, anche una
360 altra funzione, \func{fcloseall}, che serve a chiudere tutti i file, il suo
362 \begin{prototype}{stdio.h}{int fcloseall(void)}
363 Chiude tutti gli stream.
365 \bodydesc{Restituisce 0 se non ci sono errori ed \macro{EOF} altrimenti.}
367 la funzione esegue lo scarico dei dati bufferizzati in uscita e scarta quelli
368 in ingresso, chiudendo tutti i file. Questa funzione è provvista solo per i
369 casi di emergenza, quando si è verificato un errore ed il programma deve
370 essere abortito, ma si vuole compiere qualche altra operazione dopo aver
371 chiuso i file e prima di uscire (si ricordi quanto visto in
372 \secref{sec:proc_exit}).
375 \subsection{Lettura e scrittura su uno stream}
378 Una delle caratteristiche più utili dell'interfaccia degli stream è la
379 ricchezza delle funzioni disponibili per le operazioni di lettura e
380 scrittura sui file. Sono infatti previste ben tre diverse modalità
381 modalità di input/output non formattato:
383 \item\textsl{binario} in cui legge/scrive un blocco di dati alla
384 volta, vedi \secref{sec:file_binary_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 \item\textsl{di linea} in cui si legge/scrive una linea (terminata dal
389 carattere di newline \verb|\n|) alla volta, vedi
390 \secref{sec:file_line_io}.
392 ed inoltre la modalità di input/output formattato.
394 A differenza dell'interfaccia dei file descriptor, con gli stream il
395 raggiungimento della fine del file è considerato un errore, e viene
396 notificato come tale dai valori di uscita delle varie funzioni. Nella
397 maggior parte dei casi questo avviene con la restituzione del valore
398 intero (di tipo \type{int}) \macro{EOF}\footnote{la costante deve essere
399 negativa, le \acr{glibc} usano -1, altre implementazioni possono avere
400 valori diversi.} definito anch'esso nell'header \func{stdlib.h}.
402 Dato che le funzioni dell'interfaccia degli stream sono funzioni di libreria
403 che si appoggiano a delle system call, esse non settano direttamente la
404 variabile \var{errno}, che mantiene il valore settato dalla system call che ha
407 Siccome la condizione di end-of-file è anch'essa segnalata come errore, nasce
408 il problema di come distinguerla da un errore effettivo; basarsi solo sul
409 valore di ritorno della funzione e controllare il valore di \var{errno}
410 infatti non basta, dato che quest'ultimo potrebbe essere stato settato in una
411 altra occasione, (si veda \secref{sec:sys_errno} per i dettagli del
412 funzionamento di \var{errno}).
414 Per questo motivo tutte le implementazioni delle librerie standard
415 mantengono per ogni stream almeno due flag all'interno dell'oggetto
416 \type{FILE}, il flag di \textit{end-of-file}, che segnala che si è
417 raggiunta la fine del file in lettura, e quello di errore, che segnala
418 la presenza di un qualche errore nelle operazioni di input/output;
419 questi due flag possono essere riletti dalle funzioni:
422 \funcdecl{int feof(FILE *stream)}
423 Controlla il flag di end-of-file di \param{stream}.
424 \funcdecl{int ferror(FILE *stream)}
425 Controlla il flag di errore di \param{stream}.
427 Entrambe le funzioni ritornano un valore diverso da zero se i relativi
430 \noindent si tenga presente comunque che la lettura di questi flag segnala
431 soltanto che c'è stato un errore, o che si è raggiunta la fine del file in una
432 qualunque operazione sullo stream, il controllo quindi deve essere effettuato
433 ogni volta che si chiama una funzione di libreria.
435 Entrambi i flag (di errore e di end-of-file) possono essere cancellati usando
436 la funzione \func{clearerr}, il cui prototipo è:
437 \begin{prototype}{stdio.h}{void clearerr(FILE *stream)}
438 Cancella i flag di errore ed end-of-file di \param{stream}.
440 \noindent in genere si usa questa funziona una volta che si sia identificata e
441 corretta la causa di un errore per evitare di mantenere i flag attivi,
442 così da poter rilevare una successiva ulteriore condizione di errore.
445 \subsection{Input/output binario}
446 \label{sec:file_binary_io}
448 La prima modalità di input/output non formattato ricalca quella della
449 interfaccia dei file descriptor, e provvede semplicemente la scrittura e
450 la lettura dei dati da un buffer verso un file e viceversa. In generale
451 questa è la modalità che si usa quando si ha a che fare con dati non
452 formattati. Le due funzioni che si usano per l'I/O binario sono:
456 \funcdecl{size\_t fread(void * ptr, size\_t size, size\_t nmemb, FILE
459 \funcdecl{size\_t fwrite(const void * ptr, size\_t size, size\_t
460 nmemb, FILE * stream)}
462 Rispettivamente leggono e scrivono \param{nmemb} elementi di dimensione
463 \param{size} dal buffer \param{ptr} al file \param{stream}.
465 \bodydesc{Entrambe le funzioni ritornano il numero di elementi letti o
466 scritti, in caso di errore o fine del file viene restituito un numero di
467 elementi inferiore al richiesto.}
470 In genere si usano queste funzioni quando si devono trasferire su file
471 blocchi di dati binari in maniera compatta e veloce; un primo caso di uso
472 tipico è quello in cui si salva un vettore (o un certo numero dei suoi
473 elementi) con una chiamata del tipo:
474 \begin{lstlisting}[labelstep=0,frame=,indent=1cm]{}
475 int WriteVect(FILE * stream, double * vec, size_t nelem)
479 if ( (nread = fwrite(vec, size, nelem, stream)) != nelem) {
480 perror("Write error");
485 in questo caso devono essere specificate le dimensioni di ciascun
486 elemento ed il numero di quelli che si vogliono scrivere. Un secondo
487 caso è invece quello in cui si vuole trasferire su file una struttura;
488 si avrà allora una chiamata tipo:
489 \begin{lstlisting}[labelstep=0,frame=,indent=1cm]{}
496 int WriteStruct(FILE * stream, struct histogram * histo, size_t nelem)
498 if ( fwrite(vec, sizeof(*histo), 1, stream) !=1) {
499 perror("Write error");
504 in cui si specifica la dimensione dell'intera struttura ed un solo
507 In realtà quello che conta nel trasferimento dei dati sono le dimensioni
508 totali, che sono sempre pari al prodotto \func{size * nelem}; la sola
509 differenza è che le funzioni non ritornano il numero di byte scritti,
510 ma il numero di elementi.
512 La funzione \func{fread} legge sempre un numero intero di elementi, se
513 incontra la fine del file l'oggetto letto parzialmente viene scartato
514 (lo stesso avviene in caso di errore). In questo caso la posizione dello
515 stream viene settata alla fine del file (e non a quella corrispondente
516 alla quantità di dati letti).
518 In caso di errore (o fine del file per \func{fread}) entrambe le
519 funzioni restituiscono il numero di oggetti effettivamente letti o
520 scritti, che sarà inferiore a quello richiesto. Contrariamente a quanto
521 avviene per i file descriptor, questo segnala una condizione di errore e
522 occorrerà usare \func{feof} e \func{ferror} per stabilire la natura del
525 Benché queste funzioni assicurino la massima efficienza per il
526 salvataggio dei dati, i dati memorizzati attraverso di esse presentano
527 lo svantaggio di dipendere strettamente dalla piattaforma di sviluppo
528 usata ed in genere possono essere riletti senza problemi solo dallo
529 stesso programma che li ha prodotti.
531 Infatti diversi compilatori possono eseguire ottimizzazioni diverse
532 delle strutture dati e alcuni compilatori (come il \cmd{gcc}) possono
533 anche scegliere se ottimizzare l'occupazione di spazio, impacchettando
534 più strettamente i dati, o la velocità inserendo opportuni
535 \textit{padding} per l'allineamento dei medesimi generando quindi output
536 binari diversi. Inoltre altre incompatibilità si possono presentare
537 quando entrano in gioco differenze di architettura hardware, come la
538 dimensione del bus o la modalità di ordinamento dei bit o il formato
539 delle variabili in floating point.
541 Per questo motivo quando si usa l'input/output binario occorre sempre
542 essere prendere le opportune precauzioni (in genere usare un formato di
543 più alto livello che permetta di recuperare l'informazione completa),
544 per assicurarsi che versioni diverse del programma siano in grado di
545 rileggere i dati tenendo conto delle eventuali differenze.
547 Le \acr{glibc} definiscono altre due funzioni per l'I/O binario, che
548 evitano il lock implicito dello stream, usato per dalla librerie per la
549 gestione delle applicazioni multi-thread (si veda
550 \secref{sec:file_stream_thread} per i dettagli).
555 \funcdecl{size\_t fread\_unlocked(void * ptr, size\_t size, size\_t
556 nmemb, FILE * stream)}
558 \funcdecl{size\_t fwrite\_unlocked(const void * ptr, size\_t size,
559 size\_t nmemb, FILE * stream)}
561 \bodydesc{Le funzioni sono identiche alle analoghe \func{fread} e
562 \func{fwrite} ma non acquisiscono il lock implicito sullo stream.}
564 \noindent entrambe le funzioni sono estensioni GNU previste solo dalle
568 \subsection{Input/output a caratteri}
569 \label{sec:file_char_io}
571 La seconda modalità di input/output è quella a caratteri, in cui si
572 trasferisce un carattere alla volta. Le funzioni per la lettura a
573 caratteri sono tre, \func{fgetc}, \func{getc} e \func{getchar}, i
574 rispettivi prototipi sono:
578 \funcdecl{int getc(FILE *stream)} Legge un byte da \param{stream} e lo
579 restituisce come intero. In genere è implementata come una macro.
581 \funcdecl{int fgetc(FILE *stream)} Legge un byte da \param{stream} e lo
582 restituisce come intero. È una sempre una funzione.
584 \funcdecl{int getchar(void)} Equivalente a \func{getc(stdin)}.
586 \bodydesc{Tutte queste funzioni leggono un byte alla volta, che viene
587 restituito come intero; in caso di errore o fine del file il valore
588 di ritorno è \macro{EOF}.}
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.
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}).
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.
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 è:
618 \funcdecl{wint\_t getwc(FILE *stream)} Legge un carattere esteso da
619 \param{stream}. In genere è implementata come una macro.
621 \funcdecl{wint\_t fgetwc(FILE *stream)} Legge un carattere esteso da
622 \param{stream} È una sempre una funzione.
624 \funcdecl{wint\_t getwchar(void)} Equivalente a \func{getwc(stdin)}.
626 \bodydesc{Tutte queste funzioni leggono un carattere alla volta, in
627 caso di errore o fine del file il valore di ritorno è \macro{WEOF}.}
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:
636 \funcdecl{int putc(int c, FILE *stream)} Scrive il carattere \param{c}
637 su \param{stream}. In genere è implementata come una macro.
639 \funcdecl{int fputc(FILE *stream)} Scrive il carattere \param{c} su
640 \param{stream}. È una sempre una funzione.
642 \funcdecl{int putchar(void)} Equivalente a \func{putc(stdin)}.
644 \bodydesc{Le funzioni scrivono sempre un carattere alla volta, il cui
645 valore viene restituito in caso di successo; in caso di errore o
646 fine del file il valore di ritorno è \macro{EOF}.}
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
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.
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
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
670 \bodydesc{Le funzioni restituiscono la parola \param{w}, o \macro{EOF}
671 in caso di errore o di fine del file.}
673 \noindent l'uso di queste funzioni è deprecato in favore dell'uso di
674 \func{fread} e \func{fwrite}, in quanto non è possibile distinguere il
675 valore -1 da una condizione di errore che restituisce \macro{EOF}.
677 Una degli usi più frequenti dell'input/output a caratteri è nei
678 programmi di \textit{parsing} in cui si analizza il testo; in questo
679 contesto diventa utile poter analizzare il carattere successivo da uno
680 stream senza estrarlo effettivamente (la tecnica è detta \textit{peeking
681 ahead}) in modo che il programma possa regolarsi sulla base avendo
682 dato una \textsl{sbirciatina} a quello che viene dopo.
684 Nel nostro caso questo tipo di comportamento può essere realizzato prima
685 leggendo il carattere, e poi rimandandolo indietro, cosicchè ridiventi
686 disponibile per una lettura successiva; la funzione che inverte la
687 lettura si chiama \func{ungetc} ed il suo prototipo è:
688 \begin{prototype}{stdio.h}{int ungetc(int c, FILE *stream)}
689 Cancella i flag di errore ed end-of-file di \param{stream}.
696 \subsection{Input/output di linea}
697 \label{sec:file_line_io}
699 La terza ed ultima modalità di input/output non formattato è quello di
700 linea, in cui legge o scrive una riga alla volta; questa è una modalità
701 molto usata, ma che presenta le caratteristiche più controverse.
703 Le funzioni per leggere una linea sono sostazialmente due, \func{gets} e
704 \func{fgets}, i rispettivi prototipi sono:
708 \funcdecl{char * gets(char * string)} Scrive su \param{string} una
709 linea letta da \var{stdin}.
711 \funcdecl{char * fgets(char * string, int size, FILE *stream)}
712 Scrive su \param{string} la linea letta da \param{stream} per un
713 massimo di \param{size} byte.
715 \bodydesc{Le funzioni restituiscono della stringa letta o \macro{NULL}
721 \subsection{Input/output formattato}
722 \label{sec:file_formatted_io}
725 \subsection{Posizionamento su uno stream}
726 \label{sec:file_fseek}
730 \section{Funzioni avanzate}
731 \label{sec:file_stream_adv_func}
733 In questa sezione esamineremo le funzioni che permettono di controllare
734 alcune caratteristiche più particolari degli stream, come la lettura
735 degli attributi, le modalità di bufferizzazione, etc.
738 \subsection{Le funzioni di controllo}
739 \label{sec:file_stream_cntrl}
741 Al contrario di quanto avviene con i file descriptor le librerie standard del
742 C non prevedono nessuna funzione come la \func{fcntl} per la lettura degli
743 attributi degli stream; le \acr{glibc} però supportano alcune estensioni
744 derivate da Solaris, che permettono di ottenere informazioni utili.
746 In certi casi può essere necessario sapere se un certo stream è accessibile in
747 lettura o scrittura. In genere questa informazione non è disponibile, e si
748 deve ricordare come il file è stato aperto. La cosa può essere complessa se le
749 operazioni vengono effettuate in una subroutine, che a questo punto
750 necessiterà di informazioni aggiuntive rispetto al semplice puntatore allo
751 stream; questo può essere evitato con le due funzioni \func{\_\_freadable} e
752 \func{\_\_fwritable} i cui prototipi sono:
754 \headdecl{stdio\_ext.h}
755 \funcdecl{int \_\_freadable (FILE * stream)}
756 Restituisce un valore diverso da zero se \param{stream} consente la lettura.
758 \funcdecl{int \_\_fwritable(FILE * stream)}
759 Restituisce un valore diverso da zero se \param{stream} consente la
763 Altre due funzioni, \func{\_\_freading} e \func{\_\_fwriting} servono ad un
764 uso ancora più specialistico, il loro prototipo è:
766 \headdecl{stdio\_ext.h}
767 \funcdecl{int \_\_freading (FILE * stream)}
768 Restituisce un valore diverso da zero se \param{stream} è aperto in sola
769 lettura o se l'ultima operazione è stata di lettura.
771 \funcdecl{int \_\_fwriting(FILE * stream)}
772 Restituisce un valore diverso da zero se \param{stream} è aperto in sola
773 scrittura o se l'ultima operazione è stata di scrittura.
776 Le due funzioni hanno lo scopo di determinare di che tipo è stata l'ultima
777 operazione eseguita su uno stream aperto in lettura/scrittura; ovviamente se
778 uno stream è aperto in sola lettura (o sola scrittura) la modalità dell'ultima
779 operazione è sempre determinata; l'unica ambiguità è quando non sono state
780 ancora eseguite operazioni, in questo caso le funzioni rispondono come se
781 una operazione ci fosse comunque stata.
783 La conoscenza dell'ultima operazione effettuata su uno stream aperto in
784 lettura/scrittura è utile in quanto permette di trarre conclusioni sullo stato
785 del buffer e del suo contenuto.
788 \subsection{Il controllo della bufferizzazione}
789 \label{sec:file_buffering_ctrl}
791 Come accennato in \secref{sec:file_buffering} le librerie definiscono una
792 serie di funzioni che permettono di controllare il comportamento degli
796 \subsection{Gli stream e i thread}
797 \label{sec:file_stream_thread}
799 Gli stream possono essere usati in applicazioni multi-thread allo stesso
800 modo in cui sono usati nelle applicazioni normali, ma si deve essere
801 consapovoli delle possibili complicazioni anche quando non si usano i
802 thread, dato che l'implementazione delle librerie è influenzata
803 pesantemente dalle richieste necessarie per garantirne l'uso coi thread.
810 \funcdecl{void flockfile(FILE * stream)} Esegue l'acquisizione del
811 lock dello stream \param{stream}, bloccandosi in caso il lock non
814 \funcdecl{int ftrylockfile(FILE * stream)} Tenta l'acquisizione del
815 lock dello stream \param{stream}, senza bloccarsi in caso il lock non sia
816 disponibile. Ritorna zero in caso di acquisizione del lock, diverso da
819 \funcdecl{void funlockfile(FILE * stream)} Rilascia il lock dello
820 stream \param{stream}.
824 \subsection{Dettagli dell'implementazione}
825 \label{sec:file_stream_details}
828 \subsection{File temporanei}
829 \label{sec:file_temp_file}
832 \subsection{Efficienza}
833 \label{sec:file_stream_efficiency}