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