sistemate varie figure, finita prima stesura file locking POSIX
[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}.  Dopo
6 una breve sezione introduttiva tratteremo le funzioni base per la gestione
7 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 è un'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 \cite{APUE} Stevens descrive una serie di test sull'influenza delle
34 dimensioni del blocco di dati (il parametro \param{buf} di \func{read} e
35 \func{write}) nell'efficienza nelle operazioni di I/O con i file descriptor,
36 evidenziando come le prestazioni ottimali si ottengano a partire da dimensioni
37 del buffer dei dati pari a quelle dei blocchi del filesystem (il valore dato
38 dal campo \var{st\_blksize} di \var{fstat}).
39
40 Se il programmatore non si cura di effettuare le operazioni in blocchi di
41 dimensioni adeguate, le prestazioni sono inferiori.  La caratteristica
42 principale dell'interfaccia degli stream è che essa provvede da sola alla
43 gestione dei dettagli della bufferizzazione e all'esecuzione delle operazioni
44 di lettura e scrittura in blocchi di dimensioni appropriate all'ottenimento
45 della massima efficienza.
46
47 Per questo motivo l'interfaccia viene chiamata anche interfaccia dei
48 \textit{file stream}, dato che non è più necessario doversi preoccupare
49 dei dettagli della comunicazione con il tipo di hardware sottostante
50 (come nel caso della dimensione dei blocchi del filesystem), ed un file
51 può essere sempre considerato come composto da un flusso continuo (da
52 cui il nome \textit{stream}) di dati.
53
54 A parte i dettagli legati alla gestione delle operazioni di lettura e
55 scrittura (sia per quel che riguarda la bufferizzazione, che le
56 formattazioni), i file stream restano del tutto equivalenti ai file descriptor
57 (sui quali sono basati), ed in particolare continua a valere quanto visto in
58 \secref{sec:file_sharing} a proposito dell'accesso condiviso ed in
59 \secref{sec:file_access_control} per il controllo di accesso.
60
61
62 \subsection{Gli oggetti \ctyp{FILE}}
63 \label{sec:file_FILE}
64
65 Per ragioni storiche la struttura di dati che rappresenta uno stream è stata
66 chiamata \ctyp{FILE}, questi oggetti sono creati dalle funzioni di libreria e
67 contengono tutte le informazioni necessarie a gestire le operazioni sugli
68 stream, come la posizione corrente, lo stato del buffer e degli indicatori di
69 stato e di fine del file.
70
71 Per questo motivo gli utenti non devono mai utilizzare direttamente o
72 allocare queste strutture, ma usare sempre puntatori del tipo \ctyp{FILE
73   *} ottenuti dalla libreria stessa (tanto che in certi casi il termine
74 di puntatore a file è diventato sinonimo di stream).  Tutte le funzioni
75 della libreria che operano sui file accettano come parametri solo
76 variabili di questo tipo, che diventa accessibile includendo l'header
77 file \file{stdio.h}.
78
79
80
81 \subsection{Gli stream standard}
82 \label{sec:file_std_stream}
83
84 Ai tre file descriptor standard (vedi \secref{sec:file_std_descr})
85 aperti per ogni processo, corrispondono altrettanti stream, che
86 rappresentano i canali standard di input/output prestabiliti; anche
87 questi tre stream sono identificabili attraverso dei nomi simbolici
88 definiti nell'header \file{stdio.h} che sono:
89
90 \begin{basedescript}{\desclabelwidth{3.0cm}}
91 \item[\var{FILE *stdin}] Lo \textit{standard input} cioè lo stream da
92   cui il processo riceve ordinariamente i dati in ingresso. Normalmente
93   è associato dalla shell all'input del terminale e prende i caratteri
94   dalla tastiera.
95 \item[\var{FILE *stdout}] Lo \textit{standard output} cioè lo stream su
96   cui il processo invia ordinariamente i dati in uscita. Normalmente è
97   associato dalla shell all'output del terminale e scrive sullo schermo.
98 \item[\var{FILE *stderr}] Lo \textit{standard error} cioè lo stream su
99   cui il processo è supposto inviare i messaggi di errore. Normalmente
100   anch'esso è associato dalla shell all'output del terminale e scrive
101   sullo schermo.
102 \end{basedescript}
103
104 Nelle \acr{glibc} \var{stdin}, \var{stdout} e \var{stderr} sono
105 effettivamente tre variabili di tipo \ctyp{FILE *} che possono essere
106 usate come tutte le altre, ad esempio si può effettuare una redirezione
107 dell'output di un programma con il semplice codice:
108 \begin{lstlisting}[labelstep=0,frame=,indent=1cm]{}
109     fclose(stdout);
110     stdout = fopen("standard-output-file", "w");
111 \end{lstlisting}
112 ma in altri sistemi queste variabili possono essere definite da macro, e
113 se si hanno problemi di portabilità e si vuole essere sicuri, diventa
114 opportuno usare la funzione \func{freopen}.
115
116
117 \subsection{Le modalità di bufferizzazione}
118 \label{sec:file_buffering}
119
120 La bufferizzazione è una delle caratteristiche principali della
121 interfaccia degli stream; lo scopo è quello di ridurre al minimo il
122 numero di system call (\func{read} o \func{write}) eseguite nelle
123 operazioni di input/output. Questa funzionalità è assicurata
124 automaticamente dalla libreria, ma costituisce anche uno degli aspetti
125 più comunemente fraintesi, in particolare per quello che riguarda
126 l'aspetto della scrittura dei dati sul file.
127
128 I caratteri che vengono scritti su uno stream normalmente vengono
129 accumulati in un buffer e poi trasmessi in blocco in maniera asincrona
130 rispetto alla scrittura (quello che viene chiamato lo \textsl{scarico}
131 dei dati, dall'inglese \textit{flush}) tutte le volte che il buffer
132 viene riempito. Un comportamento analogo avviene anche in lettura (cioè
133 dal file viene letto un blocco di dati, anche se se ne sono richiesti
134 una quantità inferiore), ma la cosa ovviamente ha rilevanza inferiore,
135 dato che i dati letti sono sempre gli stessi; in caso di scrittura
136 invece, quando si ha un accesso contemporaneo allo stesso file (ad
137 esempio da parte di un altro processo) si potranno vedere solo le parti
138 effettivamente scritte, e non quelle ancora presenti nel buffer.
139
140 Allo stesso modo, se si sta facendo dell'input/output interattivo
141 bisognerà tenere presente le caratteristiche delle operazioni di scarico
142 dei dati, poiché non è detto che ad una scrittura sullo stream
143 corrisponda una immediata scrittura sul dispositivo.
144
145 Per rispondere ad esigenze diverse, lo standard definisce tre distinte
146 modalità in cui può essere eseguita la bufferizzazione, delle quali
147 occorre essere ben consapevoli, specie in caso di lettura e scrittura da
148 dispositivi interattivi:
149 \begin{itemize}
150 \item \textit{unbuffered}: in questo caso non c'è bufferizzazione ed i
151   caratteri vengono trasmessi direttamente al file non appena possibile
152   (effettuando immediatamente una \func{write}).
153 \item \textit{line buffered}: in questo caso i caratteri vengono
154   normalmente trasmessi al file in blocco ogni volta che viene
155   incontrato un carattere di \textit{newline} (il carattere ASCII
156   \verb|\n|).
157 \item \textit{fully buffered}: in questo caso i caratteri vengono
158   trasmessi da e verso il file in blocchi di dimensione opportuna.
159 \end{itemize}
160
161 Lo standard ANSI C specifica inoltre che lo standard output e lo
162 standard input siano aperti in modalità \textit{fully buffered} quando
163 non fanno riferimento ad un dispositivo interattivo, e che lo standard
164 error non sia mai aperto in modalità \textit{fully buffered}.
165
166 Linux, come BSD e SVr4, specifica il comportamento predefinito in maniera
167 ancora più precisa, e cioè impone che lo standard error sia sempre
168 \textit{unbuffered} (in modo che i messaggi di errore siano mostrati il più
169 rapidamente possibile) e che standard input e standard output siano aperti in
170 modalità \textit{line buffered} quando sono associati ad un terminale (od
171 altro dispositivo interattivo) ed in modalità \textit{fully buffered}
172 altrimenti.
173
174 Il comportamento specificato per standard input e standard output vale anche
175 per tutti i nuovi stream aperti da un processo; la selezione comunque avviene
176 automaticamente, e la libreria apre lo stream nella modalità più opportuna a
177 seconda del file o del dispositivo scelto.
178
179 La modalità \textit{line buffered} è quella che necessita di maggiori
180 chiarimenti e attenzioni per quel che concerne il suo funzionamento. Come già
181 accennato nella descrizione, \emph{di norma} i dati vengono inviati al kernel
182 alla ricezione di un carattere di a capo; questo non è vero in tutti i casi,
183 infatti, dato che le dimensioni del buffer usato dalle librerie sono fisse, se
184 le si eccedono si può avere uno scarico dei dati anche prima che sia stato
185 inviato un carattere di \textit{newline}.
186
187 Un secondo punto da tenere presente, particolarmente quando si ha a che fare
188 con I/O interattivo, è che quando si effettua una lettura su uno stream che
189 comporta l'accesso al kernel\footnote{questo vuol dire sempre se lo stream da
190   cui si legge è in modalità \textit{unbuffered}.} viene anche eseguito lo
191 scarico di tutti i buffer degli stream in scrittura.
192
193 In \secref{sec:file_buffering_ctrl} vedremo come la libreria definisca delle
194 opportune funzioni per controllare le modalità di bufferizzazione e lo scarico
195 dei dati.
196
197
198
199 \section{Funzioni base}
200 \label{sec:file_ansi_base_func}
201
202 Esamineremo in questa sezione le funzioni base dell'interfaccia degli stream,
203 analoghe a quelle di \secref{sec:file_base_func} per i file descriptor. In
204 particolare vedremo come aprire, leggere, scrivere e cambiare la posizione
205 corrente in uno stream.
206
207
208 \subsection{Apertura e chiusura di uno stream}
209 \label{sec:file_fopen}
210
211 Le funzioni che si possono usare per aprire uno stream sono solo tre:
212 \func{fopen}, \func{fdopen} e \func{freopen},\footnote{\func{fopen} e
213   \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 *stream)}
222   Apre il file specificato da \param{path} associandolo allo stream
223   specificato da \param{stream}, se questo è già aperto prima lo chiude.
224   
225   \bodydesc{Le funzioni ritornano un puntatore valido in caso di successo e
226     \macro{NULL} in caso di errore, in tal caso \var{errno} assumerà il valore
227     ricevuto dalla funzione sottostante di cui è fallita l'esecuzione.
228   
229     Gli errori pertanto possono essere quelli di \code{malloc} per tutte
230     e tre le funzioni, quelli \func{open} per \func{fopen}, quelli di
231     \func{fcntl} per \func{fdopen} e quelli di \func{fopen},
232     \func{fclose} e \func{fflush} per \func{freopen}.}
233 \end{functions}
234
235 Normalmente la funzione che si usa per aprire uno stream è \func{fopen},
236 essa apre il file specificato nella modalità specificata da
237 \param{mode}, che è una stringa che deve iniziare con almeno uno dei
238 valori indicati in \tabref{tab:file_fopen_mode} (sono possibili varie
239 estensioni che vedremo in seguito).
240
241 L'uso più comune di \func{freopen} è per redirigere uno dei tre file
242 standard (vedi \secref{sec:file_std_stream}): il file \param{path} viene
243 associato a \param{stream} e se questo è uno stream già aperto viene
244 preventivamente chiuso.
245
246 Infine \func{fdopen} viene usata per associare uno stream ad un file
247 descriptor esistente ottenuto tramite una altra funzione (ad esempio con
248 una \func{open}, una \func{dup}, o una \func{pipe}) e serve quando si
249 vogliono usare gli stream con file come le fifo o i socket, che non
250 possono essere aperti con le funzioni delle librerie standard del C.
251
252 \begin{table}[htb]
253   \centering
254   \footnotesize
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     \texttt{b} & specifica che il file è binario, non ha alcun effetto. \\
278     \texttt{x} & la apertura fallisce se il file esiste già. \\
279     \hline
280   \end{tabular}
281   \caption{Modalità di apertura di uno stream dello standard ANSI C che
282     sono sempre presenti in qualunque sistema POSIX.}
283   \label{tab:file_fopen_mode}
284 \end{table}
285
286 In realtà lo standard ANSI C prevede un totale di 15 possibili valori
287 diversi per \param{mode}, ma in \tabref{tab:file_fopen_mode} si sono
288 riportati solo i sei valori effettivi, ad essi può essere aggiunto pure
289 il carattere \texttt{b} (come ultimo carattere o nel mezzo agli altri per
290 le stringhe di due caratteri) che in altri sistemi operativi serve a
291 distinguere i file binari dai file di testo; in un sistema POSIX questa
292 distinzione non esiste e il valore viene accettato solo per
293 compatibilità, ma non ha alcun effetto.
294
295 Le \acr{glibc} supportano alcune estensioni, queste devono essere sempre
296 indicate dopo aver specificato il \param{mode} con uno dei valori di
297 \tabref{tab:file_fopen_mode}. L'uso del carattere \texttt{x} serve per
298 evitare di sovrascrivere un file già esistente (è analoga all'uso
299 dell'opzione \macro{O\_EXCL} in \func{open}), se il file specificato già
300 esiste e si aggiunge questo carattere a \param{mode} la \func{fopen}
301 fallisce. 
302
303 Un'altra estensione serve a supportare la localizzazione, quando si
304 aggiunge a \param{mode} una stringa della forma \verb|",ccs=STRING"| il
305 valore \verb|STRING| è considerato il nome di una codifica dei caratteri
306 e \func{fopen} marca il file per l'uso dei caratteri estesi e abilita le
307 opportune funzioni di conversione in lettura e scrittura.
308
309 Nel caso si usi \func{fdopen} i valori specificati da \param{mode} devono
310 essere compatibili con quelli con cui il file descriptor è stato aperto.
311 Inoltre i modi \cmd{w} e \cmd{w+} non troncano il file. La posizione nello
312 stream viene impostata a quella corrente nel file descriptor, e le variabili di
313 errore e di fine del file (vedi \secref{sec:file_io}) sono cancellate. Il file
314 non viene duplicato e verrà chiuso alla chiusura dello stream.
315
316 I nuovi file saranno creati secondo quanto visto in
317 \secref{sec:file_ownership} ed avranno i permessi di accesso impostati 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}).
321
322 In caso di file aperti in lettura e scrittura occorre ricordarsi che c'è
323 di mezzo una bufferizzazione; per questo motivo lo standard ANSI C
324 richiede che ci sia un'operazione di posizionamento fra un'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. 
328
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 un'operazione nominalmente nulla come \code{fseek(file, 0, SEEK\_CUR)} è
335 sufficiente a garantire la sincronizzazione.
336
337 Una volta aperto lo stream, si può cambiare la modalità di bufferizzazione
338 (si veda \secref{sec:file_buffering_ctrl}) fintanto che non si è effettuato
339 alcuna operazione di I/O sul file.
340
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}. 
344   
345   \bodydesc{Restituisce 0 in caso di successo e \macro{EOF} in caso di errore,
346     nel qual caso imposta \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
349     \func{fflush}).}
350 \end{prototype}
351
352 La funzione effettua lo scarico di tutti i dati presenti nei buffer di uscita
353 e scarta tutti i dati in ingresso; se era stato allocato un buffer per lo
354 stream questo verrà rilasciato. La funzione effettua lo scarico solo per i
355 dati presenti nei buffer in user space usati dalle \acr{glibc}; se si vuole
356 essere sicuri che il kernel forzi la scrittura su disco occorrerà effettuare
357 una \func{sync} (vedi \secref{sec:file_sync}).
358
359 Linux supporta anche una altra funzione, \func{fcloseall}, come estensione GNU
360 implementata dalle \acr{glibc}, accessibile avendo definito
361 \macro{\_GNU\_SOURCE}, il suo prototipo è:
362 \begin{prototype}{stdio.h}{int fcloseall(void)}
363   Chiude tutti gli stream. 
364   
365   \bodydesc{Restituisce 0 se non ci sono errori ed \macro{EOF} altrimenti.}
366 \end{prototype}
367 \noindent la funzione esegue lo scarico dei dati bufferizzati in uscita
368 e scarta quelli in ingresso, chiudendo tutti i file. Questa funzione è
369 provvista solo per i casi di emergenza, quando si è verificato un errore
370 ed il programma deve essere abortito, ma si vuole compiere qualche altra
371 operazione dopo aver chiuso i file e prima di uscire (si ricordi quanto
372 visto in \secref{sec:proc_exit}).
373
374
375 \subsection{Lettura e scrittura su uno stream}
376 \label{sec:file_io}
377
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:
382 \begin{enumerate*}
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}.
391 \end{enumerate*}
392 ed inoltre la modalità di input/output formattato.
393
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 \ctyp{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 \file{stdlib.h}.
401
402 Dato che le funzioni dell'interfaccia degli stream sono funzioni di libreria
403 che si appoggiano a delle system call, esse non impostano direttamente la
404 variabile \var{errno}, che mantiene il valore impostato dalla system call che
405 ha riportato l'errore.
406
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 impostato in
411 una altra occasione, (si veda \secref{sec:sys_errno} per i dettagli del
412 funzionamento di \var{errno}).
413
414 Per questo motivo tutte le implementazioni delle librerie standard
415 mantengono per ogni stream almeno due flag all'interno dell'oggetto
416 \ctyp{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:
420 \begin{functions}
421   \headdecl{stdio.h}
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}.
426   
427   \bodydesc{Entrambe le funzioni ritornano un valore diverso da zero se
428     i relativi flag sono impostati.}
429 \end{functions}
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.
434
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}. 
439 \end{prototype}
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, così da
442 poter rilevare una successiva ulteriore condizione di errore. Di questa
443 funzione esiste una analoga \func{clearerr\_unlocked} che non esegue il blocco
444 dello stream (vedi \secref{sec:file_stream_thread}).
445
446
447 \subsection{Input/output binario}
448 \label{sec:file_binary_io}
449
450 La prima modalità di input/output non formattato ricalca quella della
451 interfaccia dei file descriptor, e provvede semplicemente la scrittura e
452 la lettura dei dati da un buffer verso un file e viceversa. In generale
453 questa è la modalità che si usa quando si ha a che fare con dati non
454 formattati. Le due funzioni che si usano per l'I/O binario sono:
455 \begin{functions}
456   \headdecl{stdio.h} 
457   
458   \funcdecl{size\_t fread(void *ptr, size\_t size, size\_t nmemb, FILE
459     *stream)}
460   
461   \funcdecl{size\_t fwrite(const void *ptr, size\_t size, size\_t
462     nmemb, FILE *stream)}
463   
464   Rispettivamente leggono e scrivono \param{nmemb} elementi di dimensione
465   \param{size} dal buffer \param{ptr} al file \param{stream}.
466   
467   \bodydesc{Entrambe le funzioni ritornano il numero di elementi letti o
468     scritti, in caso di errore o fine del file viene restituito un numero di
469     elementi inferiore al richiesto.}
470 \end{functions}
471
472 In genere si usano queste funzioni quando si devono trasferire su file
473 blocchi di dati binari in maniera compatta e veloce; un primo caso di uso
474 tipico è quello in cui si salva un vettore (o un certo numero dei suoi
475 elementi) con una chiamata del tipo:
476 %\footnotesize
477 \begin{lstlisting}[labelstep=0,frame=,indent=1cm]{}
478 int WriteVect(FILE *stream, double *vec, size_t nelem) 
479 {
480     int size, nread;
481     size = sizeof(*vec);
482     if ( (nread = fwrite(vec, size, nelem, stream)) != nelem) {
483         perror("Write error");
484     }
485     return nread;
486 }
487 \end{lstlisting}
488 %\normalsize
489 in questo caso devono essere specificate le dimensioni di ciascun
490 elemento ed il numero di quelli che si vogliono scrivere. Un secondo
491 caso è invece quello in cui si vuole trasferire su file una struttura;
492 si avrà allora una chiamata tipo:
493 %\footnotesize
494 \begin{lstlisting}[labelstep=0,frame=,indent=1cm]{}
495 struct histogram {
496     int nbins; 
497     double max, min;
498     double *bin;
499 } histo; 
500
501 int WriteStruct(FILE *stream, struct histogram *histo, size_t nelem) 
502 {
503     if ( fwrite(vec, sizeof(*histo), 1, stream) !=1) {
504         perror("Write error");
505     }
506     return nread;
507 }
508 \end{lstlisting}
509 %\normalsize
510 in cui si specifica la dimensione dell'intera struttura ed un solo
511 elemento. 
512
513 In realtà quello che conta nel trasferimento dei dati sono le dimensioni
514 totali, che sono sempre pari al prodotto \code{size * nelem}; la sola
515 differenza è che le funzioni non ritornano il numero di byte scritti,
516 ma il numero di elementi.
517
518 La funzione \func{fread} legge sempre un numero intero di elementi, se
519 incontra la fine del file l'oggetto letto parzialmente viene scartato
520 (lo stesso avviene in caso di errore). In questo caso la posizione dello
521 stream viene impostata alla fine del file (e non a quella corrispondente
522 alla quantità di dati letti).
523
524 In caso di errore (o fine del file per \func{fread}) entrambe le
525 funzioni restituiscono il numero di oggetti effettivamente letti o
526 scritti, che sarà inferiore a quello richiesto. Contrariamente a quanto
527 avviene per i file descriptor, questo segnala una condizione di errore e
528 occorrerà usare \func{feof} e \func{ferror} per stabilire la natura del
529 problema.
530
531 Benché queste funzioni assicurino la massima efficienza per il
532 salvataggio dei dati, i dati memorizzati attraverso di esse presentano
533 lo svantaggio di dipendere strettamente dalla piattaforma di sviluppo
534 usata ed in genere possono essere riletti senza problemi solo dallo
535 stesso programma che li ha prodotti.
536
537 Infatti diversi compilatori possono eseguire ottimizzazioni diverse
538 delle strutture dati e alcuni compilatori (come il \cmd{gcc}) possono
539 anche scegliere se ottimizzare l'occupazione di spazio, impacchettando
540 più strettamente i dati, o la velocità inserendo opportuni
541 \textit{padding} per l'allineamento dei medesimi generando quindi output
542 binari diversi. Inoltre altre incompatibilità si possono presentare
543 quando entrano in gioco differenze di architettura hardware, come la
544 dimensione del bus o la modalità di ordinamento dei bit o il formato
545 delle variabili in floating point.
546
547 Per questo motivo quando si usa l'input/output binario occorre sempre
548 essere prendere le opportune precauzioni (in genere usare un formato di
549 più alto livello che permetta di recuperare l'informazione completa),
550 per assicurarsi che versioni diverse del programma siano in grado di
551 rileggere i dati tenendo conto delle eventuali differenze.
552
553 Le \acr{glibc} definiscono altre due funzioni per l'I/O binario, che
554 evitano il lock implicito dello stream, usato per dalla librerie per la
555 gestione delle applicazioni multi-thread (si veda
556 \secref{sec:file_stream_thread} per i dettagli):
557 \begin{functions}
558   \headdecl{stdio.h}
559   
560   \funcdecl{size\_t fread\_unlocked(void *ptr, size\_t size, size\_t
561     nmemb, FILE *stream)}
562   
563   \funcdecl{size\_t fwrite\_unlocked(const void *ptr, size\_t size,
564     size\_t nmemb, FILE *stream)}
565   
566   \bodydesc{Le funzioni sono identiche alle analoghe \func{fread} e
567     \func{fwrite} ma non acquisiscono il lock implicito sullo stream.}
568 \end{functions}
569 \noindent entrambe le funzioni sono estensioni GNU previste solo dalle
570 \acr{glibc}.
571
572
573 \subsection{Input/output a caratteri}
574 \label{sec:file_char_io}
575
576 La seconda modalità di input/output è quella a caratteri, in cui si
577 trasferisce un carattere alla volta.  Le funzioni per la lettura a
578 caratteri sono tre, \func{fgetc}, \func{getc} e \func{getchar}, i
579 rispettivi prototipi sono:
580 \begin{functions}
581   \headdecl{stdio.h} 
582
583   \funcdecl{int getc(FILE *stream)} Legge un byte da \param{stream} e lo
584   restituisce come intero. In genere è implementata come una macro. 
585   
586   \funcdecl{int fgetc(FILE *stream)} Legge un byte da \param{stream} e lo
587   restituisce come intero. È sempre una funzione.
588   
589   \funcdecl{int getchar(void)} Equivalente a \code{getc(stdin)}.
590   
591   \bodydesc{Tutte queste funzioni leggono un byte alla volta, che viene
592     restituito come intero; in caso di errore o fine del file il valore
593     di ritorno è \macro{EOF}.}
594 \end{functions}
595
596 A parte \func{getchar}, che si usa in genere per leggere un carattere da
597 tastiera, le altre due funzioni sono sostanzialmente equivalenti. La
598 differenza è che \func{getc} è ottimizzata al massimo e normalmente
599 viene implementata con una macro, per cui occorre stare attenti a cosa
600 le si passa come argomento, infatti \param{stream} può essere valutato
601 più volte nell'esecuzione, e non viene passato in copia con il
602 meccanismo visto in \secref{sec:proc_var_passing}; per questo motivo se
603 si passa un'espressione si possono avere effetti indesiderati.
604
605 Invece \func{fgetc} è assicurata essere sempre una funzione, per questo
606 motivo la sua esecuzione normalmente è più lenta per via dell'overhead
607 della chiamata, ma è altresì possibile ricavarne l'indirizzo, che può
608 essere passato come parametro ad un altra funzione (e non si hanno i
609 problemi accennati in precedenza con \param{stream}).
610
611 Le tre funzioni restituiscono tutte un \ctyp{unsigned char} convertito
612 ad \ctyp{int} (si usa \ctyp{unsigned char} in modo da evitare
613 l'espansione del segno). In questo modo il valore di ritorno è sempre
614 positivo, tranne in caso di errore o fine del file.
615
616 Nelle estensioni GNU che provvedono la localizzazione sono definite tre
617 funzioni equivalenti alle precedenti che invece di un carattere di un
618 byte restituiscono un carattere in formato esteso (cioè di tipo
619 \ctyp{wint\_t}, il loro prototipo è:
620 \begin{functions}
621   \headdecl{stdio.h} 
622   \headdecl{wchar.h} 
623   
624   \funcdecl{wint\_t getwc(FILE *stream)} Legge un carattere esteso da
625   \param{stream}. In genere è implementata come una macro.
626   
627   \funcdecl{wint\_t fgetwc(FILE *stream)} Legge un carattere esteso da
628   \param{stream} È una sempre una funzione.
629   
630   \funcdecl{wint\_t getwchar(void)} Equivalente a \code{getwc(stdin)}.
631   
632   \bodydesc{Tutte queste funzioni leggono un carattere alla volta, in
633     caso di errore o fine del file il valore di ritorno è \macro{WEOF}.}
634 \end{functions}
635
636 Per scrivere un carattere si possono usare tre funzioni analoghe alle
637 precedenti usate per leggere: \func{putc}, \func{fputc} e
638 \func{putchar}; i loro prototipi sono:
639 \begin{functions}
640   \headdecl{stdio.h} 
641   
642   \funcdecl{int putc(int c, FILE *stream)} Scrive il carattere \param{c}
643   su \param{stream}. In genere è implementata come una macro.
644   
645   \funcdecl{int fputc(FILE *stream)} Scrive il carattere \param{c} su
646   \param{stream}. È una sempre una funzione.
647   
648   \funcdecl{int putchar(void)} Equivalente a \code{putc(stdin)}.
649   
650   \bodydesc{Le funzioni scrivono sempre un carattere alla volta, il cui
651     valore viene restituito in caso di successo; in caso di errore o
652     fine del file il valore di ritorno è \macro{EOF}.}
653 \end{functions}
654
655 Tutte queste funzioni scrivono sempre un byte alla volta, anche se
656 prendono come parametro un \ctyp{int} (che pertanto deve essere ottenuto
657 con un cast da un \ctyp{unsigned char}). Anche il valore di ritorno è
658 sempre un intero; in caso di errore o fine del file il valore di ritorno
659 è \macro{EOF}.
660
661 Come nel caso dell'I/O binario le \acr{glibc} provvedono per ciascuna
662 delle funzioni precedenti, come estensione GNU, una seconda funzione, il
663 cui nome è ottenuto aggiungendo un \code{\_unlocked}, che esegue
664 esattamente le stesse operazioni evitando però il lock implicito dello
665 stream.
666
667 Per compatibilità con SVID sono provviste anche due funzioni per leggere
668 e scrivere una \textit{word} (che è sempre definita come \ctyp{int}); i
669 loro prototipi sono:
670 \begin{functions}
671   \headdecl{stdio.h} 
672   
673   \funcdecl{int getw(FILE *stream)} Legge una parola da \param{stream}.
674   \funcdecl{int putw(int w, FILE *stream)} Scrive la parola \param{w} su
675   \param{stream}.
676   
677   \bodydesc{Le funzioni restituiscono la parola \param{w}, o \macro{EOF}
678     in caso di errore o di fine del file.}
679 \end{functions}
680 \noindent l'uso di queste funzioni è deprecato in favore dell'uso di
681 \func{fread} e \func{fwrite}, in quanto non è possibile distinguere il
682 valore -1 da una condizione di errore che restituisce \macro{EOF}.
683
684 Una degli usi più frequenti dell'input/output a caratteri è nei
685 programmi di \textit{parsing} in cui si analizza il testo; in questo
686 contesto diventa utile poter analizzare il carattere successivo da uno
687 stream senza estrarlo effettivamente (la tecnica è detta \textit{peeking
688   ahead}) in modo che il programma possa regolarsi sulla base avendo
689 dato una \textsl{sbirciatina} a quello che viene dopo. 
690
691 Nel nostro caso questo tipo di comportamento può essere realizzato prima
692 leggendo il carattere, e poi rimandandolo indietro, cosicché ridiventi
693 disponibile per una lettura successiva; la funzione che inverte la
694 lettura si chiama \func{ungetc} ed il suo prototipo è:
695 \begin{prototype}{stdio.h}{int ungetc(int c, FILE *stream)}
696   Rimanda indietro il carattere \param{c}, con un cast a \ctyp{unsigned
697     char}, sullo stream \param{stream}.
698
699   \bodydesc{La funzione ritorna \param{c} in caso di successo e
700   \macro{EOF} in caso di errore.}
701 \end{prototype}
702 \noindent benché lo standard ANSI C preveda che l'operazione possa
703 essere ripetuta per un numero arbitrario di caratteri, alle
704 implementazioni è richiesto di garantire solo un livello; questo è
705 quello che fa la \acr{glibc}, che richiede che avvenga un'altra
706 operazione fra due \func{ungetc} successive.
707
708 Non è necessario che il carattere che si manda indietro sia l'ultimo che
709 si è letto, e non è necessario neanche avere letto nessun carattere
710 prima di usare \func{ungetc}, ma di norma la funzione è intesa per
711 essere usata per rimandare indietro l'ultimo carattere letto.
712
713 Nel caso \param{c} sia un \macro{EOF} la funzione non fa nulla, e
714 restituisce sempre \macro{EOF}; così si può usare \func{ungetc} anche
715 con il risultato di una lettura alla fine del file.
716
717 Se si è alla fine del file si può comunque rimandare indietro un
718 carattere, il flag di end-of-file verrà automaticamente cancellato
719 perché c'è un nuovo carattere disponibile che potrà essere riletto
720 successivamente.
721
722 Infine si tenga presente che \func{ungetc} non altera il contenuto del
723 file, ma opera esclusivamente sul buffer interno. Se si esegue una
724 qualunque delle operazioni di riposizionamento (vedi
725 \secref{sec:file_fseek}) i caratteri rimandati indietro vengono
726 scartati.
727
728
729 \subsection{Input/output di linea}
730 \label{sec:file_line_io}
731
732 La terza ed ultima modalità di input/output non formattato è quella di
733 linea, in cui legge o scrive una riga alla volta; questa è una modalità
734 molto usata per l'I/O da terminale, ma che presenta le caratteristiche
735 più controverse.
736
737 Le funzioni previste dallo standard ANSI C per leggere una linea sono
738 sostanzialmente due, \func{gets} e \func{fgets}, i cui rispettivi
739 prototipi sono:
740 \begin{functions}
741   \headdecl{stdio.h} 
742   
743   \funcdecl{char *gets(char *string)} Scrive su \param{string} una
744   linea letta da \var{stdin}.
745   
746   \funcdecl{char *fgets(char *string, int size, FILE *stream)}
747   Scrive su \param{string} la linea letta da \param{stream} per un
748   massimo di \param{size} byte.
749   
750   \bodydesc{Le funzioni restituiscono l'indirizzo \param{string} in caso
751     di successo o \macro{NULL} in caso di errore.}
752 \end{functions}
753
754 Entrambe le funzioni effettuano la lettura (dal file specificato \func{fgets},
755 dallo standard input \func{gets}) di una linea di caratteri (terminata dal
756 carattere \textit{newline}, \verb|\n|, quello mappato sul tasto di ritorno a
757 capo della tastiera), ma \func{gets} sostituisce \verb|\n| con uno zero,
758 mentre \func{fgets} aggiunge uno zero dopo il \textit{newline}, che resta
759 dentro la stringa. Se la lettura incontra la fine del file (o c'è un errore)
760 viene restituito un \macro{NULL}, ed il buffer \param{buf} non viene toccato.
761 L'uso di \func{gets} è deprecato e deve essere assolutamente evitato; la
762 funzione infatti non controlla il numero di byte letti, per cui nel caso
763 la stringa letta superi le dimensioni del buffer, si avrà un
764 \textit{buffer overflow}, con sovrascrittura della memoria del processo
765 adiacente al buffer. 
766
767 Questa è una delle vulnerabilità più sfruttate per guadagnare accessi
768 non autorizzati al sistema (i cosiddetti \textit{exploit}), basta
769 infatti inviare una stringa sufficientemente lunga ed opportunamente
770 forgiata per sovrascrivere gli indirizzi di ritorno nello stack
771 (supposto che la \func{gets} sia stata chiamata da una subroutine), in
772 modo da far ripartire l'esecuzione nel codice inviato nella stringa
773 stessa (in genere uno \textit{shell code} cioè una sezione di programma
774 lancia una shell).
775
776 La funzione \func{fgets} non ha i precedenti problemi di \func{gets} in
777 quanto prende in input la dimensione del buffer \param{size}, che non
778 verrà mai ecceduta in lettura. La funzione legge fino ad un massimo di
779 \param{size} caratteri (newline compreso), ed aggiunge uno zero di
780 terminazione; questo comporta che la stringa possa essere al massimo di
781 \var{size-1} caratteri.  Se la linea eccede la dimensione del buffer
782 verranno letti solo \var{size-1} caratteri, ma la stringa sarà sempre
783 terminata correttamente con uno zero finale; sarà possibile leggere i
784 restanti caratteri in una chiamata successiva.
785
786 Per la scrittura di una linea lo standard ANSI C prevede altre due
787 funzioni, \func{fputs} e \func{puts}, analoghe a quelle di lettura, i
788 rispettivi prototipi sono:
789 \begin{functions}
790   \headdecl{stdio.h} 
791   
792   \funcdecl{int puts(const char *string)} Scrive su \var{stdout} la
793   linea \param{string}.
794   
795   \funcdecl{int fputs(const char *string, FILE *stream)} Scrive su
796   \param{stream} la linea \param{string}.
797   
798   \bodydesc{Le funzioni restituiscono un valore non negativo in caso di
799     successo o \macro{EOF} in caso di errore.}
800 \end{functions}
801
802 Dato che in questo caso si scrivono i dati in uscita \func{puts} non ha i
803 problemi di \func{gets} ed è in genere la forma più immediata per scrivere
804 messaggi sullo standard output; la funzione prende una stringa terminata da
805 uno zero ed aggiunge automaticamente il ritorno a capo. La differenza con
806 \func{fputs} (a parte la possibilità di specificare un file diverso da
807 \var{stdout}) è che quest'ultima non aggiunge il newline, che deve essere
808 previsto esplicitamente.
809
810 Come per le funzioni di input/output a caratteri esistono le estensioni
811 per leggere e scrivere caratteri estesi, i loro prototipi sono:
812 \begin{functions}
813   \headdecl{wchar.h} 
814   \funcdecl{wchar\_t *fgetws(wchar\_t *ws, int n, FILE *stream)}
815   Legge un massimo di \param{n} caratteri estesi dal file
816   \param{stream} al buffer \param{ws}.
817   
818   \funcdecl{int fputws(const wchar\_t *ws, FILE *stream)} Scrive la
819   linea \param{ws} di caratteri estesi sul file \param{stream}.
820   
821   \bodydesc{Le funzioni ritornano rispettivamente \param{ws} o un numero
822     non negativo in caso di successo e \macro{NULL} o \macro{EOF} in
823     caso di errore o fine del file.}
824 \end{functions}
825 \noindent il comportamento è identico a quello di \func{fgets} e
826 \func{fputs} solo che tutto (numero di caratteri massimo, terminatore
827 della stringa, newline) è espresso in termini di caratteri estesi
828 anziché di caratteri ASCII.
829
830 Come nel caso dell'I/O binario e a caratteri nelle \acr{glibc} sono
831 previste una serie di altre funzioni, estensione di tutte quelle
832 illustrate finora (eccetto \func{gets} e \func{puts}), il cui nome si
833 ottiene aggiungendo un \code{\_unlocked}, e che eseguono esattamente le
834 stesse operazioni delle loro equivalenti, evitando però il lock
835 implicito dello stream (vedi \secref{sec:file_stream_thread}).
836
837 Come abbiamo visto, le funzioni di lettura per l'input/output di linea
838 previste dallo standard ANSI C presentano svariati inconvenienti. Benché
839 \func{fgets} non abbia i gravissimi problemi di \func{gets}, può
840 comunque dare risultati ambigui se l'input contiene degli zeri; questi
841 infatti saranno scritti sul buffer di uscita e la stringa in output
842 apparirà come più corta dei byte effettivamente letti. Questa è una
843 condizione che è sempre possibile controllare (deve essere presente un
844 newline prima della effettiva conclusione della stringa presente nel
845 buffer), ma a costo di una complicazione ulteriore della logica del
846 programma. Lo stesso dicasi quando si deve gestire il caso di stringa
847 che eccede le dimensioni del buffer.
848
849 Per questo motivo le \acr{glibc} prevedono, come estensione GNU, due
850 nuove funzioni per la gestione dell'input/output di linea, il cui uso
851 permette di risolvere questi problemi. L'uso di queste funzioni deve
852 essere attivato definendo la macro \macro{\_GNU\_SOURCE} prima di
853 includere \file{stdio.h}. La prima delle due, \func{getline}, serve per
854 leggere una linea terminata da un newline esattamente allo stesso modo
855 di \func{fgets}, il suo prototipo è:
856 \begin{prototype}{stdio.h}
857   {ssize\_t getline(char **buffer, size\_t *n, FILE *stream)} Legge una
858   linea dal file \param{stream} sul buffer indicato da \param{buffer}
859   riallocandolo se necessario (l'indirizzo del buffer e la sua
860   dimensione vengono sempre riscritte).
861
862   \bodydesc{La funzione ritorna il numero di caratteri letti in caso di
863   successo e -1 in caso di errore o di raggiungimento della fine del
864   file.}
865 \end{prototype}
866
867 La funzione permette di eseguire una lettura senza doversi preoccupare
868 della eventuale lunghezza eccessiva della stringa da leggere. Essa
869 prende come primo parametro l'indirizzo del puntatore al buffer su cui
870 si vuole leggere la linea. Quest'ultimo \emph{deve} essere stato
871 allocato in precedenza con una \func{malloc} (non si può passare
872 l'indirizzo di un puntatore ad una variabile locale); come secondo
873 parametro la funzione vuole l'indirizzo della variabile contenente le
874 dimensioni del buffer suddetto.
875
876 Se il buffer di destinazione è sufficientemente ampio la stringa viene
877 scritta subito, altrimenti il buffer viene allargato usando
878 \func{realloc} e la nuova dimensione ed il nuovo puntatore vengono
879 passata indietro (si noti infatti come per entrambi i parametri si siano
880 usati dei \textit{value result argument}, passando dei puntatori anzichè
881 i valori delle variabili, secondo la tecnica spiegata in
882 \secref{sec:proc_var_passing}).
883
884 Se si passa alla funzione l'indirizzo ad un puntatore impostato a
885 \macro{NULL} e \var{*n} è zero, la funzione provvede da sola
886 all'allocazione della memoria necessaria a contenere la linea. In tutti
887 i casi si ottiene dalla funzione un puntatore all'inizio del testo della
888 linea. Un esempio di codice può essere il seguente:
889 \begin{lstlisting}[labelstep=0,frame=,indent=1cm]{}
890     size_t n = 0; 
891     char *ptr = NULL;
892     int nread;
893     FILE * file;
894     ...    
895     nread = getline(&ptr, &n, file);
896 \end{lstlisting}
897 e per evitare memory leak occorre ricordarsi di liberare \var{ptr} con
898 una \func{free}.
899
900 Il valore di ritorno della funzione indica il numero di caratteri letti
901 dallo stream (quindi compreso il newline, ma non lo zero di
902 terminazione); questo permette anche di distinguere eventuali zeri letti
903 dallo stream da quello inserito dalla funzione per terminare la linea.
904 Se si è alla fine del file e non si è potuto leggere nulla o c'è stato
905 un errore la funzione restituisce -1.
906
907 La seconda estensione GNU è una generalizzazione di \func{getline} per
908 poter usare come separatore un carattere qualsiasi, la funzione si
909 chiama \func{getdelim} ed il suo prototipo è:
910 \begin{prototype}{stdio.h}
911 {ssize\_t getdelim(char **buffer, size\_t *n, int delim, FILE *stream)} 
912   Identica a \func{getline} solo che usa \param{delim} al posto del
913   carattere di newline come separatore di linea.
914 \end{prototype}
915
916 Il comportamento di \func{getdelim} è identico a quello di \func{getline} (che
917 può essere implementata da questa passando \verb|'\n'| come valore di
918 \param{delim}).
919
920
921 \subsection{L'input/output formattato}
922 \label{sec:file_formatted_io}
923
924 L'ultima modalità di input/output è quella formattata, che è una delle
925 caratteristiche più utilizzate delle librerie standard del C; in genere questa
926 è la modalità in cui si esegue normalmente l'output su terminale poiché
927 permette di stampare in maniera facile e veloce dati, tabelle e messaggi.
928
929 L'output formattato viene eseguito con una delle 13 funzioni della famiglia
930 \func{printf}; le tre più usate sono le seguenti:
931 \begin{functions}
932   \headdecl{stdio.h} 
933   \funcdecl{int printf(const char *format, ...)} Stampa su \file{stdout}
934   gli argomenti, secondo il formato specificato da \param{format}.
935   
936   \funcdecl{int fprintf(FILE *stream, const char *format, ...)}  Stampa
937   su \param{stream} gli argomenti, secondo il formato specificato da
938   \param{format}.
939   
940   \funcdecl{int sprintf(char *str, const char *format, ...)} Stampa
941   sulla stringa \param{str} gli argomenti, secondo il formato
942   specificato da \param{format}.
943
944   \bodydesc{Le funzioni ritornano il numero di caratteri stampati.}
945 \end{functions}
946 \noindent le prime due servono per stampare su file (lo standard output
947 o quello specificato) la terza permette di stampare su una stringa, in genere
948 l'uso di \func{sprintf} è sconsigliato in quanto è possibile, se non si ha la
949 sicurezza assoluta sulle dimensioni del risultato della stampa, eccedere le
950 dimensioni di \param{str} con conseguente sovrascrittura di altre variabili e
951 possibili buffer overflow; per questo motivo si consiglia l'uso
952 dell'alternativa:
953 \begin{prototype}{stdio.h}
954 {snprintf(char *str, size\_t size, const char *format, ...)} 
955   Identica a \func{sprintf}, ma non scrive su \param{str} più di
956   \param{size} caratteri.
957 \end{prototype}
958
959 La parte più complessa di queste funzioni è il formato della stringa
960 \param{format} che indica le conversioni da fare, da cui poi deriva il numero
961 dei parametri che dovranno essere passati a seguire. 
962
963 \begin{table}[htb]
964   \centering
965   \footnotesize
966   \begin{tabular}[c]{|l|l|p{10cm}|}
967     \hline
968     \textbf{Valore} & \textbf{Tipo} & \textbf{Significato} \\
969     \hline
970     \hline
971    \cmd{\%d} &\ctyp{int}         & Stampa un numero intero in formato decimale
972                                    con segno \\
973    \cmd{\%i} &\ctyp{int}         & Identico a \cmd{\%i} in output, \\
974    \cmd{\%o} &\ctyp{unsigned int}& Stampa un numero intero come ottale\\
975    \cmd{\%u} &\ctyp{unsigned int}& Stampa un numero intero in formato
976                                    decimale senza segno \\
977    \cmd{\%x}, 
978    \cmd{\%X} &\ctyp{unsigned int}& Stampano un intero in formato esadecimale,
979                                    rispettivamente con lettere minuscole e
980                                    maiuscole. \\
981    \cmd{\%f} &\ctyp{unsigned int}& Stampa un numero in virgola mobile con la
982                                    notazione a virgola fissa \\
983    \cmd{\%e}, 
984    \cmd{\%E} &\ctyp{double} & Stampano un numero in virgola mobile con la
985                               notazione esponenziale, rispettivamente con
986                               lettere minuscole e maiuscole. \\
987    \cmd{\%g}, 
988    \cmd{\%G} &\ctyp{double} & Stampano un numero in virgola mobile con la
989                               notazione più appropriate delle due precedenti,
990                               rispettivamente con lettere minuscole e
991                               maiuscole. \\
992    \cmd{\%a}, 
993    \cmd{\%A} &\ctyp{double} & Stampano un numero in virgola mobile in
994                               notazione esadecimale frazionaria\\
995    \cmd{\%c} &\ctyp{int}    & Stampa un carattere singolo\\
996    \cmd{\%s} &\ctyp{char *} & Stampa una stringa \\
997    \cmd{\%p} &\ctyp{void *} & Stampa il valore di un puntatore\\
998    \cmd{\%n} &\ctyp{\&int}  & Prende il numero di caratteri stampati finora\\
999    \cmd{\%\%}&              & Stampa un \% \\
1000     \hline
1001   \end{tabular}
1002   \caption{Valori possibili per gli specificatori di conversione in una
1003     stringa di formato di \func{printf}.} 
1004   \label{tab:file_format_spec}
1005 \end{table}
1006
1007 La stringa è costituita da caratteri normali (tutti eccetto \texttt{\%}), che
1008 vengono passati invariati all'output, e da direttive di conversione, in cui
1009 devono essere sempre presenti il carattere \texttt{\%}, che introduce la
1010 direttiva, ed uno degli specificatori di conversione (riportati in
1011 \tabref{tab:file_format_spec}) che la conclude.
1012
1013 \begin{table}[htb]
1014   \centering
1015   \footnotesize
1016   \begin{tabular}[c]{|l|p{10cm}|}
1017     \hline
1018     \textbf{Valore} & \textbf{Significato}\\
1019     \hline
1020     \hline
1021     \cmd{\#} & Chiede la conversione in forma alternativa. \\
1022     \cmd{0}  & La conversione è riempita con zeri alla sinistra del valore.\\
1023     \cmd{-}  & La conversione viene allineata a sinistra sul bordo del campo.\\
1024     \cmd{' '}& Mette uno spazio prima di un numero con segno di valore 
1025                positivo\\
1026     \cmd{+}  & Mette sempre il segno ($+$ o $-$) prima di un numero.\\
1027     \hline
1028   \end{tabular}
1029   \caption{I valori dei flag per il formato di \func{printf}}
1030   \label{tab:file_format_flag}
1031 \end{table}
1032
1033 Il formato di una direttiva di conversione prevede una serie di possibili
1034 elementi opzionali oltre al \cmd{\%} e allo specificatore di conversione. In
1035 generale essa è sempre del tipo:
1036 \begin{center}
1037 \begin{verbatim}
1038 % [n. parametro $] [flag] [[larghezza] [. precisione]] [tipo] conversione
1039 \end{verbatim}
1040 \end{center}
1041 in cui tutti i valori tranne il \cmd{\%} e lo specificatore di conversione
1042 sono opzionali (e per questo sono indicati fra parentesi quadre); si possono
1043 usare più elementi opzionali, nel qual caso devono essere specificati in
1044 questo ordine:
1045 \begin{itemize*}
1046 \item uno specificatore del parametro da usare (terminato da un \cmd{\$}),
1047 \item uno o più flag (i cui valori possibili sono riassunti in
1048   \tabref{tab:file_format_flag}) che controllano il formato di stampa della
1049   conversione
1050 \item uno specificatore di larghezza (un numero decimale), eventualmente
1051   seguito (per i numeri in virgola mobile) da un specificatore di precisione
1052   (un altro numero decimale),
1053 \item uno specificatore del tipo di dato, che ne indica la dimensione (i cui
1054   valori possibili sono riassunti in \tabref{tab:file_format_type}).
1055 \end{itemize*}
1056
1057
1058 Dettagli ulteriori sulle varie opzioni possono essere trovati nella pagina di
1059 manuale di \func{printf} e nella documentazione delle \acr{glibc}.
1060
1061 \begin{table}[htb]
1062   \centering
1063   \footnotesize
1064   \begin{tabular}[c]{|l|p{10cm}|}
1065     \hline
1066     \textbf{Valore} & \textbf{Significato} \\
1067     \hline
1068     \hline
1069     \cmd{hh} & una conversione intera corrisponde a un \ctyp{char} con o senza
1070                segno, o il puntatore per il numero dei parametri \cmd{n} è di 
1071                tipo \ctyp{char}.\\
1072     \cmd{h}  & una conversione intera corrisponde a uno \ctyp{short} con o 
1073                senza segno, o il puntatore per il numero dei parametri \cmd{n}
1074                è di tipo \ctyp{short}.\\
1075     \cmd{l}  & una conversione intera corrisponde a un \ctyp{long} con o 
1076                senza segno, o il puntatore per il numero dei parametri \cmd{n}
1077                è di tipo \ctyp{long}, o il carattere o la stringa seguenti
1078                sono in formato esteso.\\ 
1079     \cmd{ll} & una conversione intera corrisponde a un \ctyp{long long} con o 
1080                senza segno, o il puntatore per il numero dei parametri \cmd{n}
1081                è di tipo \ctyp{long long}.\\
1082     \cmd{L}  & una conversione in virgola mobile corrisponde a un
1083                \ctyp{double}.\\
1084     \cmd{q}  & sinonimo di \cmd{ll}.\\
1085     \cmd{j}  & una conversione intera corrisponde a un \type{intmax\_t} o 
1086                \type{uintmax\_t}.\\
1087     \cmd{z}  & una conversione intera corrisponde a un \type{size\_t} o 
1088                \type{ssize\_t}.\\
1089     \cmd{t}  & una conversione intera corrisponde a un \type{ptrdiff\_t}.\\
1090     \hline
1091   \end{tabular}
1092   \caption{Il modificatore di tipo di dato per il formato di \func{printf}}
1093   \label{tab:file_format_type}
1094 \end{table}
1095
1096 Una versione alternativa delle funzioni di output formattato, che permettono
1097 di usare il puntatore ad una lista di argomenti (vedi
1098 \secref{sec:proc_variadic}), sono le seguenti:
1099 \begin{functions}
1100   \headdecl{stdio.h} 
1101   
1102   \funcdecl{int vprintf(const char *format, va\_list ap)} Stampa su
1103   \var{stdout} gli argomenti della lista \param{ap}, secondo il formato
1104   specificato da \param{format}.
1105   
1106   \funcdecl{int vfprintf(FILE *stream, const char *format, va\_list ap)}
1107   Stampa su \param{stream} gli argomenti della lista \param{ap}, secondo il
1108   formato specificato da \param{format}.
1109   
1110   \funcdecl{int vsprintf(char *str, const char *format, va\_list ap)} Stampa
1111   sulla stringa \param{str} gli argomenti della lista \param{ap}, secondo il
1112   formato specificato da \param{format}.
1113
1114   \bodydesc{Le funzioni ritornano il numero di caratteri stampati.}
1115 \end{functions}
1116 \noindent con queste funzioni diventa possibile selezionare gli argomenti che
1117 si vogliono passare ad una routine di stampa, passando direttamente la lista
1118 tramite il parametro \param{ap}. Per poter far questo ovviamente la lista dei
1119 parametri dovrà essere opportunamente trattata (l'argomento è esaminato in
1120 \secref{sec:proc_variadic}), e dopo l'esecuzione della funzione l'argomento
1121 \param{ap} non sarà più utilizzabile (in generale dovrebbe essere eseguito un
1122 \macro{va\_end(ap)} ma in Linux questo non è necessario). 
1123
1124 Come per \func{sprintf} anche per \func{vsprintf} esiste una analoga
1125 \func{vsnprintf} che pone un limite sul numero di caratteri che vengono
1126 scritti sulla stringa di destinazione:
1127 \begin{prototype}{stdio.h}
1128 {vsnprintf(char *str, size\_t size, const char *format, va\_list ap)} 
1129   Identica a \func{vsprintf}, ma non scrive su \param{str} più di
1130   \param{size} caratteri.
1131 \end{prototype}
1132 \noindent in modo da evitare possibili buffer overflow.
1133
1134
1135 Per eliminare alla radice questi problemi, le \acr{glibc} supportano una
1136 estensione specifica GNU che alloca dinamicamente tutto lo spazio necessario;
1137 l'estensione si attiva al solito definendo \macro{\_GNU\_SOURCE}, le due
1138 funzioni sono:
1139 \begin{functions}
1140   \headdecl{stdio.h} 
1141     
1142   \funcdecl{int asprintf(char **strptr, const char *format, ...)}  Stampa gli
1143   argomenti specificati secondo il formato specificato da \param{format} su
1144   una stringa allocata automaticamente all'indirizzo \param{*strptr}.
1145   
1146   \funcdecl{int vasprintf(char **strptr, const char *format, va\_list ap)}
1147   Stampa gli argomenti della lista \param{ap} secondo il formato specificato
1148   da \param{format} su una stringa allocata automaticamente all'indirizzo
1149   \param{*strptr}.
1150
1151   \bodydesc{Le funzioni ritornano il numero di caratteri stampati.}
1152 \end{functions}
1153 Entrambe le funzioni prendono come parametro \param{strptr} che deve essere
1154 l'indirizzo di un puntatore ad una stringa di caratteri, in cui verrà
1155 restituito (si ricordi quanto detto in \secref{sec:proc_var_passing} a
1156 proposito dei \textit{value result argument}) l'indirizzo della stringa
1157 allocata automaticamente dalle funzioni. Occorre inoltre ricordarsi di
1158 invocare \func{free} per liberare detto puntatore quando la stringa non serve
1159 più, onde evitare memory leak.
1160
1161 Infine una ulteriore estensione GNU definisce le due funzioni \func{dprintf} e
1162 \func{vdprintf}, che prendono un file descriptor al posto dello stream. Altre
1163 estensioni permettono di scrivere con caratteri estesi. Anche queste funzioni,
1164 il cui nome è generato dalle precedenti funzioni aggiungendo una \texttt{w}
1165 davanti a \texttt{print}, sono trattate in dettaglio nella documentazione delle
1166 \acr{glibc}.
1167
1168 In corrispondenza alla famiglia di funzioni \func{printf} che si usano per
1169 l'output formattato, l'input formattato viene eseguito con le funzioni della
1170 famiglia \func{scanf}; fra queste le tre più importanti sono:
1171 \begin{functions}
1172   \headdecl{stdio.h} \funcdecl{int scanf(const char *format, ...)} Esegue una
1173   scansione di \file{stdin} cercando una corrispondenza di quanto letto con il
1174   formato dei dati specificato da \param{format}, ed effettua le relative
1175   conversione memorizzando il risultato nei parametri seguenti.
1176   
1177   \funcdecl{int fscanf(FILE *stream, const char *format, ...)}  Analoga alla
1178   precedente, ma effettua la scansione su \param{stream}.
1179   
1180   \funcdecl{int sscanf(char *str, const char *format, ...)} Analoga alle
1181   precedenti, ma effettua la scansione dalla stringa \param{str}.
1182   
1183   \bodydesc{Le funzioni ritornano il numero di elementi assegnati. Questi
1184     possono essere in numero inferiore a quelli specificati, ed anche zero.
1185     Quest'ultimo valore significa che non si è trovata corrispondenza. In caso
1186     di errore o fine del file viene invece restituito \macro{EOF}.}
1187 \end{functions}
1188 \noindent e come per le analoghe funzioni di scrittura esistono le relative
1189 \func{vscanf}, \func{vfscanf} \func{vsscanf} che usano un puntatore ad una
1190 lista di argomenti.
1191
1192 Tutte le funzioni della famiglia delle \func{scanf} vogliono come argomenti i
1193 puntatori alle variabili che dovranno contenere le conversioni; questo è un
1194 primo elemento di disagio in quanto è molto facile dimenticarsi di questa
1195 caratteristica.
1196
1197 Le funzioni leggono i caratteri dallo stream (o dalla stringa) di input ed
1198 eseguono un confronto con quanto indicato in \param{format}, la sintassi di
1199 questo parametro è simile a quella usata per l'analogo di \func{printf}, ma ci
1200 sono varie differenze.  Le funzioni di input infatti sono più orientate verso
1201 la lettura di testo libero che verso un input formattato in campi fissi. Uno
1202 spazio in \param{format} corrisponde con un numero qualunque di caratteri di
1203 separazione (che possono essere spazi, tabulatori, virgole etc.), mentre
1204 caratteri diversi richiedono una corrispondenza esatta. Le direttive di
1205 conversione sono analoghe a quelle di \func{printf} e si trovano descritte in
1206 dettaglio nelle pagine di manuale e nel manuale delle \acr{glibc}.
1207
1208 Le funzioni eseguono la lettura dall'input, scartano i separatori (e gli
1209 eventuali caratteri diversi indicati dalla stringa di formato) effettuando le
1210 conversioni richieste; in caso la corrispondenza fallisca (o la funzione non
1211 sia in grado di effettuare una delle conversioni richieste) la scansione viene
1212 interrotta immediatamente e la funzione ritorna lasciando posizionato lo
1213 stream al primo carattere che non corrisponde.
1214
1215 Data la notevole complessità di uso di queste funzioni, che richiedono molta
1216 cura nella definizione delle corrette stringhe di formato e sono facilmente
1217 soggette ad errori, e considerato anche il fatto che è estremamente macchinoso
1218 recuperare in caso di fallimento nelle corrispondenze, l'input formattato non
1219 è molto usato. In genere infatti quando si ha a che fare con un input
1220 relativamente semplice si preferisce usare l'input di linea ed effettuare
1221 scansione e conversione di quanto serve direttamente con una delle funzioni di
1222 conversione delle stringhe; se invece il formato è più complesso diventa più
1223 facile utilizzare uno strumento come il \cmd{flex} per generare un
1224 analizzatore lessicale o il \cmd{bison} per generare un parser.
1225
1226
1227 \subsection{Posizionamento su uno stream}
1228 \label{sec:file_fseek}
1229
1230 Come per i file descriptor è possibile anche con gli stream spostarsi
1231 all'interno di un file per effettuare operazioni di lettura o scrittura in un
1232 punto prestabilito; questo fintanto che l'operazione di riposizionamento è
1233 supportata dal file sottostante lo stream, quando cioè si ha a che fare con
1234 quello che viene detto un file ad \textsl{accesso casuale}.
1235
1236 In GNU/Linux ed in generale in ogni sistema unix-like la posizione nel file è
1237 espressa da un intero positivo, rappresentato dal tipo \type{off\_t}, il
1238 problema è alcune delle funzioni usate per il riposizionamento sugli stream
1239 originano dalle prime versioni di Unix, in cui questo tipo non era ancora
1240 stato definito, e che in altri sistemi non è detto che la posizione su un file
1241 venga sempre rappresentata con il numero di caratteri dall'inizio (ad esempio
1242 in VMS può essere rappresentata come numero di record, e offset rispetto al
1243 record corrente).
1244
1245 Tutto questo comporta la presenza di diverse funzioni che eseguono
1246 sostanzialmente le stesse operazioni, ma usano parametri di tipo
1247 diverso. Le funzioni tradizionali usate per il riposizionamento della
1248 posizione in uno stream sono:
1249 \begin{functions}
1250   \headdecl{stdio.h} 
1251   
1252   \funcdecl{int fseek(FILE *stream, long offset, int whence)} Sposta la
1253   posizione nello stream secondo quanto specificato tramite \param{offset}
1254   e \param{whence}.  
1255
1256   \funcdecl{void rewind(FILE *stream)} Riporta la posizione nello stream
1257   all'inizio del file.
1258 \end{functions}
1259
1260 L'uso di \func{fseek} è del tutto analogo a quello di \func{lseek} per i file
1261 descriptor, ed i parametri, a parte il tipo, hanno lo stesso significato; in
1262 particolare \param{whence} assume gli stessi valori già visti in
1263 \secref{sec:file_lseek}.  La funzione restituisce 0 in caso di successo e -1
1264 in caso di errore.  La funzione \func{rewind} riporta semplicemente la
1265 posizione corrente all'inizio dello stream, ma non esattamente equivalente ad
1266 una \code{fseek(stream, 0L, SEEK\_SET)} in quanto vengono cancellati anche i
1267 flag di errore e fine del file.
1268
1269 Per ottenere la posizione corrente si usa invece la funzione \func{ftell}, il
1270 cui prototipo è:
1271 \begin{prototype}{stdio.h}{long ftell(FILE *stream)} 
1272   Legge la posizione attuale nello stream \param{stream}.
1273   
1274   \bodydesc{La funzione restituisce la posizione corrente, o -1 in caso
1275     di fallimento, che può esser dovuto sia al fatto che il file non
1276     supporta il riposizionamento che al fatto che la posizione non può
1277     essere espressa con un \ctyp{long int}}
1278 \end{prototype}
1279 \noindent la funzione restituisce la posizione come numero di byte
1280 dall'inizio dello stream. 
1281
1282 Queste funzioni esprimono tutte la posizione nel file come un \func{long int},
1283 dato che (ad esempio quando si usa un filesystem indicizzato a 64 bit) questo
1284 può non essere possibile lo standard POSIX ha introdotto le nuove funzioni
1285 \func{fgetpos} e \func{fsetpos}, che invece usano il nuovo tipo
1286 \type{fpos\_t}, ed i cui prototipi sono:
1287 \begin{functions}
1288   \headdecl{stdio.h} 
1289   
1290   \funcdecl{int fsetpos(FILE *stream, fpos\_t *pos)} Imposta la posizione
1291   corrente nello stream \param{stream} al valore specificato da \param{pos}.
1292   
1293   \funcdecl{int fgetpos(FILE *stream, fpos\_t *pos)} Scrive la posizione
1294   corrente nello stream \param{stream} in \param{pos}.
1295   
1296   \bodydesc{Le funzioni ritornano 0 in caso di successo e -1 in caso di
1297     errore.}
1298 \end{functions}
1299
1300 In Linux, a partire dalle glibc 2.1, sono presenti anche le due funzioni
1301 \func{fseeko} e \func{ftello}, che assolutamente identiche alle precedenti
1302 \func{fseek} e \func{ftell} ma hanno argomenti di tipo \type{off\_t} anziché
1303 di tipo \ctyp{long int}.
1304
1305
1306
1307 \section{Funzioni avanzate}
1308 \label{sec:file_stream_adv_func}
1309
1310 In questa sezione esamineremo alcune funzioni avanzate che permettono di
1311 eseguire operazioni particolari sugli stream, come leggerne gli attributi,
1312 controllarne le modalità di bufferizzazione, gestire direttamente i lock
1313 impliciti per la programmazione multi thread.
1314
1315
1316 \subsection{Le funzioni di controllo}
1317 \label{sec:file_stream_cntrl}
1318
1319 Al contrario di quanto avviene con i file descriptor le librerie standard del
1320 C non prevedono nessuna funzione come la \func{fcntl} per il controllo degli
1321 attributi dei file. Però siccome ogni stream si appoggia ad un file descriptor
1322 si può usare la funzione \func{fileno} per ottenere quest'ultimo, il prototipo
1323 della funzione è:
1324 \begin{prototype}{stdio.h}{int fileno(FILE *stream)}
1325   Legge il file descriptor sottostante lo stream \param{stream}.
1326   
1327   \bodydesc{Restituisce il numero del file descriptor in caso di successo, e
1328     -1 qualora \param{stream} non sia valido, nel qual caso imposta
1329     \var{errno} a \macro{EBADF}.}
1330 \end{prototype}
1331 \noindent ed in questo modo diventa possibile usare direttamente \func{fcntl}.
1332
1333 Questo permette di accedere agli attributi del file descriptor sottostante lo
1334 stream, ma non ci da nessuna informazione riguardo alle proprietà dello stream
1335 medesimo.  Le \acr{glibc} però supportano alcune estensioni derivate da
1336 Solaris, che permettono di ottenere informazioni utili.
1337
1338 Ad esempio in certi casi può essere necessario sapere se un certo stream è
1339 accessibile in lettura o scrittura. In genere questa informazione non è
1340 disponibile, e si deve ricordare come il file è stato aperto. La cosa può
1341 essere complessa se le operazioni vengono effettuate in una subroutine, che a
1342 questo punto necessiterà di informazioni aggiuntive rispetto al semplice
1343 puntatore allo stream; questo può essere evitato con le due funzioni
1344 \func{\_\_freadable} e \func{\_\_fwritable} i cui prototipi sono:
1345 \begin{functions}
1346   \headdecl{stdio\_ext.h}
1347   \funcdecl{int \_\_freadable(FILE *stream)}
1348   Restituisce un valore diverso da zero se \param{stream} consente la lettura.
1349
1350   \funcdecl{int \_\_fwritable(FILE *stream)}  
1351   Restituisce un valore diverso da zero se \param{stream} consente la
1352   scrittura.
1353 \end{functions}
1354 \noindent che permettono di ottenere questa informazione.
1355
1356 La conoscenza dell'ultima operazione effettuata su uno stream aperto è utile
1357 in quanto permette di trarre conclusioni sullo stato del buffer e del suo
1358 contenuto. Altre due funzioni, \func{\_\_freading} e \func{\_\_fwriting}
1359 servono a tale scopo, il loro prototipo è:
1360 \begin{functions}
1361   \headdecl{stdio\_ext.h}
1362   \funcdecl{int \_\_freading(FILE *stream)}
1363   Restituisce un valore diverso da zero se \param{stream} è aperto in sola
1364   lettura o se l'ultima operazione è stata di lettura.
1365
1366   \funcdecl{int \_\_fwriting(FILE *stream)}  
1367   Restituisce un valore diverso da zero se \param{stream} è aperto in sola
1368   scrittura o se l'ultima operazione è stata di scrittura.
1369 \end{functions}
1370
1371 Le due funzioni permettono di determinare di che tipo è stata l'ultima
1372 operazione eseguita su uno stream aperto in lettura/scrittura; ovviamente se
1373 uno stream è aperto in sola lettura (o sola scrittura) la modalità dell'ultima
1374 operazione è sempre determinata; l'unica ambiguità è quando non sono state
1375 ancora eseguite operazioni, in questo caso le funzioni rispondono come se una
1376 operazione ci fosse comunque stata.
1377
1378
1379 \subsection{Il controllo della bufferizzazione}
1380 \label{sec:file_buffering_ctrl}
1381
1382 Come accennato in \secref{sec:file_buffering} le librerie definiscono una
1383 serie di funzioni che permettono di controllare il comportamento degli stream;
1384 se non si è specificato nulla la modalità di buffering viene decisa
1385 autonomamente sulla base del tipo di file sottostante, ed i buffer vengono
1386 allocati automaticamente.
1387
1388 Però una volta che si sia aperto lo stream (ma prima di aver compiuto
1389 operazioni su di esso) è possibile intervenire sulle modalità di buffering; la
1390 funzione che permette di controllare la bufferizzazione è \func{setvbuf}, il
1391 suo prototipo è:
1392 \begin{prototype}{stdio.h}{int setvbuf(FILE *stream, char *buf, int mode, 
1393     size\_t size)}
1394   
1395   Imposta la bufferizzazione dello stream \param{stream} nella modalità
1396   indicata da \param{mode}, usando \param{buf} come buffer di lunghezza
1397   \param{size}.
1398   
1399   \bodydesc{Restituisce zero in caso di successo, ed un valore qualunque in
1400     caso di errore, nel qual caso \var{errno} viene impostata opportunamente.}
1401 \end{prototype}
1402
1403 La funzione permette di controllare tutti gli aspetti della bufferizzazione;
1404 l'utente può specificare un buffer da usare al posto di quello allocato dal
1405 sistema passandone alla funzione l'indirizzo in \param{buf} e la dimensione in
1406 \param{size}. 
1407
1408 Ovviamente se si usa un buffer specificato dall'utente questo deve essere
1409 stato allocato e restare disponibile per tutto il tempo in cui si opera sullo
1410 stream. In genere conviene allocarlo con \func{malloc} e disallocarlo dopo la
1411 chiusura del file; ma fintanto che il file è usato all'interno di una
1412 funzione, può anche essere usata una variabile automatica. In \file{stdio.h}
1413 definita la macro \macro{BUFSIZ}, che indica le dimensioni generiche del
1414 buffer di uno stream; queste vengono usate dalla funzione \func{setbuf},
1415 questa però non è detto corrisponda in tutti i casi al valore ottimale (che
1416 può variare a seconda del dispositivo).
1417
1418 Dato che la procedura di allocazione manuale è macchinosa, comporta dei rischi
1419 (come delle scritture accidentali sul buffer) e non assicura la scelta delle
1420 dimensioni ottimali, è sempre meglio lasciare allocare il buffer alle funzioni
1421 di libreria, che sono in grado di farlo in maniera ottimale e trasparente
1422 all'utente (in quanto la disallocazione avviene automaticamente). Inoltre
1423 siccome alcune implementazioni usano parte del buffer per mantenere delle
1424 informazioni di controllo, non è detto che le dimensioni dello stesso
1425 coincidano con quelle su cui viene effettuato l'I/O.
1426
1427 \begin{table}[htb]
1428   \centering
1429   \footnotesize
1430     \begin{tabular}[c]{|l|l|}
1431       \hline
1432       \textbf{Valore} & \textbf{Modalità} \\
1433       \hline
1434       \hline
1435       \macro{\_IONBF} & \textit{unbuffered}\\
1436       \macro{\_IOLBF} & \textit{line buffered}\\
1437       \macro{\_IOFBF} & \textit{fully buffered}\\
1438       \hline
1439     \end{tabular}
1440   \caption{Valori del parametro \param{mode} di \func{setvbuf} 
1441     per l'impostazione delle modalità di bufferizzazione.}
1442   \label{tab:file_stream_buf_mode}
1443 \end{table}
1444
1445 Per evitare che \func{setvbuf} imposti il buffer basta passare un valore
1446 \macro{NULL} per \param{buf} e la funzione ignorerà il parametro \param{size}
1447 usando il buffer allocato automaticamente dal sistema.  Si potrà comunque
1448 modificare la modalità di bufferizzazione, passando in \param{mode} uno degli
1449 opportuni valori elencati in \tabref{tab:file_stream_buf_mode}. Qualora si
1450 specifichi la modalità non bufferizzata i valori di \param{buf} e \param{size}
1451 vengono sempre ignorati.
1452
1453 Oltre a \func{setvbuf} le \acr{glibc} definiscono altre tre funzioni per la
1454 gestione della bufferizzazione di uno stream: \func{setbuf}, \func{setbuffer}
1455 e \func{setlinebuf}, i loro prototipi sono:
1456 \begin{functions}
1457   \headdecl{stdio.h} 
1458   
1459   \funcdecl{void setbuf(FILE *stream, char *buf)} Disabilita la
1460   bufferizzazione se \param{buf} è \macro{NULL}, altrimenti usa \param{buf}
1461   come buffer di dimensione \macro{BUFSIZ} in modalità \textit{fully buffered}.
1462   
1463   \funcdecl{void setbuffer(FILE *stream, char *buf, size\_t size)} Disabilita
1464   la bufferizzazione se \param{buf} è \macro{NULL}, altrimenti usa \param{buf}
1465   come buffer di dimensione \param{size} in modalità \textit{fully buffered}.
1466   
1467   \funcdecl{void setlinebuf(FILE *stream)} Pone lo stream in modalità
1468   \textit{line buffered}.
1469 \end{functions}
1470 \noindent tutte queste funzioni sono realizzate con opportune chiamate a
1471 \func{setvbuf} e sono definite solo per compatibilità con le vecchie librerie
1472 BSD. Infine le \acr{glibc} provvedono le funzioni non standard\footnote{anche
1473   queste funzioni sono originarie di Solaris.} \func{\_\_flbf} e
1474 \func{\_\_fbufsize} che permettono di leggere le proprietà di bufferizzazione
1475 di uno stream; i cui prototipi sono:
1476 \begin{functions}
1477   \headdecl{stdio\_ext.h} 
1478   
1479   \funcdecl{int \_\_flbf(FILE *stream)} Restituisce un valore diverso da zero
1480   se \param{stream} è in modalità \textit{line buffered}.
1481   
1482   \funcdecl{size\_t \_\_fbufsize(FILE *stream)} Restituisce le dimensioni del
1483   buffer di \param{stream}.
1484 \end{functions}
1485
1486 Come già accennato, indipendentemente dalla modalità di bufferizzazione
1487 scelta, si può forzare lo scarico dei dati sul file con la funzione
1488 \func{fflush}, il suo prototipo è:
1489 \begin{prototype}{stdio.h}{int fflush(FILE *stream)}
1490   
1491   Forza la scrittura di tutti i dati bufferizzati dello stream \param{stream}.
1492   
1493   \bodydesc{Restituisce zero in caso di successo, ed \macro{EOF} in caso di
1494     errore, impostando \var{errno} a \macro{EBADF} se \param{stream} non è
1495     aperto o non è aperto in scrittura, o ad uno degli errori di
1496     \func{write}.}
1497 \end{prototype}
1498 \noindent anche di questa funzione esiste una analoga
1499 \func{fflush\_unlocked}\footnote{accessibile definendo \macro{\_BSD\_SOURCE} o
1500   \macro{\_SVID\_SOURCE} o \macro{\_GNU\_SOURCE}.} che non effettua il blocco
1501 dello stream.
1502
1503 Se \param{stream} è \macro{NULL} lo scarico dei dati è forzato per tutti gli
1504 stream aperti. Esistono però circostanze, ad esempio quando si vuole essere
1505 sicuri che sia stato eseguito tutto l'output su terminale, in cui serve poter
1506 effettuare lo scarico dei dati solo per gli stream in modalità line buffered;
1507 per questo motivo le \acr{glibc} supportano una estensione di Solaris, la
1508 funzione \func{\_flushlbf}, il cui prototipo è:
1509 \begin{prototype}{stdio-ext.h}{void \_flushlbf(void)}
1510   Forza la scrittura di tutti i dati bufferizzati degli stream in modalità
1511   line buffered.
1512 \end{prototype}
1513
1514 Si ricordi comunque che lo scarico dei dati dai buffer effettuato da queste
1515 funzioni non comporta la scrittura di questi su disco; se si vuole che il
1516 kernel dia effettivamente avvio alle operazioni di scrittura su disco occorre
1517 usare \func{sync} o \func{fsync} (si veda~\secref{sec:file_sync}).
1518
1519 Infine esistono anche circostanze in cui si vuole scartare tutto l'output
1520 pendente, per questo si può usare \func{fpurge}, il cui prototipo è:
1521 \begin{prototype}{stdio.h}{int fpurge(FILE *stream)}
1522  
1523   Cancella i buffer di input e di output dello stream \param{stream}.
1524   
1525   \bodydesc{Restituisce zero in caso di successo, ed \macro{EOF} in caso di
1526     errore.}
1527 \end{prototype}
1528
1529 La funzione scarta tutti i dati non ancora scritti (se il file è aperto in
1530 scrittura), e tutto l'input non ancora letto (se è aperto in lettura),
1531 compresi gli eventuali caratteri rimandati indietro con \func{ungetc}.
1532
1533
1534 \subsection{Gli stream e i thread}
1535 \label{sec:file_stream_thread}
1536
1537 Gli stream possono essere usati in applicazioni multi-thread allo stesso
1538 modo in cui sono usati nelle applicazioni normali, ma si deve essere
1539 consapevoli delle possibili complicazioni anche quando non si usano i
1540 thread, dato che l'implementazione delle librerie è influenzata
1541 pesantemente dalle richieste necessarie per garantirne l'uso coi thread.
1542
1543 Lo standard POSIX richiede che le operazioni sui file siano atomiche rispetto
1544 ai thread, per questo le operazioni sui buffer effettuate dalle funzioni di
1545 libreria durante la lettura e la scrittura di uno stream devono essere
1546 opportunamente protette (in quanto il sistema assicura l'atomicità solo per le
1547 system call). Questo viene fatto associando ad ogni stream un opportuno blocco
1548 che deve essere implicitamente acquisito prima dell'esecuzione di qualunque
1549 operazione.
1550
1551 Ci sono comunque situazioni in cui questo non basta, come quando un thread
1552 necessita di compiere più di una operazione sullo stream atomicamente, per
1553 questo motivo le librerie provvedono anche delle funzioni che permettono la
1554 gestione esplicita dei blocchi sugli stream; queste funzioni sono disponibili
1555 definendo \macro{\_POSIX\_THREAD\_SAFE\_FUNCTIONS} ed i loro prototipi sono:
1556 \begin{functions}
1557   \headdecl{stdio.h}
1558   
1559   \funcdecl{void flockfile(FILE *stream)} Esegue l'acquisizione del
1560   lock dello stream \param{stream}, bloccandosi in caso il lock non
1561   disponibile. 
1562   
1563   \funcdecl{int ftrylockfile(FILE *stream)} Tenta l'acquisizione del
1564   lock dello stream \param{stream}, senza bloccarsi in caso il lock non sia
1565   disponibile. Ritorna zero in caso di acquisizione del lock, diverso da
1566   zero altrimenti.
1567   
1568   \funcdecl{void funlockfile(FILE *stream)} Rilascia il lock dello
1569   stream \param{stream}.
1570 \end{functions}
1571 \noindent con queste funzioni diventa possibile acquisire un blocco ed
1572 eseguire tutte le operazioni volute, per poi rilasciarlo. 
1573
1574 Ma, vista la complessità delle strutture di dati coinvolte, le operazioni di
1575 blocco non sono del tutto indolori, e quando il locking dello stream non è
1576 necessario (come in tutti i programmi che non usano i thread), tutta la
1577 procedura può comportare dei costi pesanti in termini di prestazioni. Per
1578 questo motivo abbiamo visto come alle usuali funzioni di I/O non formattato
1579 siano associate delle versioni \code{\_unlocked} (alcune previste dallo stesso
1580 standard POSIX, altre aggiunte come estensioni dalle \acr{glibc}) che possono
1581 essere usate quando il locking non serve\footnote{in certi casi dette funzioni
1582   possono essere usate, visto che sono molto più efficienti, anche in caso di
1583   necessità di locking, una volta che questo sia stato acquisito manualmente.}
1584 con prestazioni molto più elevate, dato che spesso queste versioni (come
1585 accade per \func{getc} e \func{putc}) sono realizzate come macro.
1586
1587 La sostituzione di tutte le funzioni di I/O con le relative versioni
1588 \code{\_unlocked} in un programma che non usa i thread è però un lavoro
1589 abbastanza noioso; per questo motivo le \acr{glibc} provvedono al
1590 programmatore pigro un'altra via\footnote{anche questa mutuata da estensioni
1591   introdotte in Solaris.} da poter utilizzare per disabilitare in blocco il
1592 locking degli stream: l'uso della funzione \func{\_\_fsetlocking}, il cui
1593 prototipo è:
1594 \begin{prototype}{stdio\_ext.h}{int \_\_fsetlocking (FILE *stream, int type)}
1595   Specifica o richiede a seconda del valore di \param{type} la modalità in cui
1596   le operazioni di I/O su \param{stream} vengono effettuate rispetto
1597   all'acquisizione implicita del blocco sullo stream.
1598
1599   \bodydesc{Restituisce lo stato di locking interno dello stream con uno dei
1600   valori \macro{FSETLOCKING\_INTERNAL} o \macro{FSETLOCKING\_BYCALLER}.}
1601 \end{prototype}
1602
1603 La funzione imposta o legge lo stato della modalità di operazione di uno stream
1604 nei confronti del locking a seconda del valore specificato con \param{type},
1605 che può essere uno dei seguenti:
1606 \begin{basedescript}{\desclabelwidth{4.0cm}}
1607 \item[\macro{FSETLOCKING\_INTERNAL}] Lo stream userà da ora in poi il blocco
1608   implicito predefinito.
1609 \item[\macro{FSETLOCKING\_BYCALLER}] Al ritorno della funzione sarà l'utente a
1610   dover gestire da solo il locking dello stream.
1611 \item[\macro{FSETLOCKING\_QUERY}] Restituisce lo stato corrente della modalità
1612   di blocco dello stream.
1613 \end{basedescript}
1614
1615
1616 %%% Local Variables: 
1617 %%% mode: latex
1618 %%% TeX-master: "gapil"
1619 %%% End: