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