3 %% Copyright (C) 2000-2012 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 "Un preambolo",
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
12 \chapter{I file: l'interfaccia standard ANSI C}
13 \label{cha:files_std_interface}
15 Esamineremo in questo capitolo l'interfaccia standard ANSI C per i file,
16 quella che viene comunemente detta interfaccia dei \textit{file stream} o
17 anche più brevemente degli \textit{stream}. Dopo una breve sezione
18 introduttiva tratteremo le funzioni base per la gestione dell'input/output,
19 mentre tratteremo le caratteristiche più avanzate dell'interfaccia nell'ultima
23 \section{Introduzione}
24 \label{sec:file_stream_intro}
26 Come visto in cap.~\ref{cha:file_unix_interface} le operazioni di I/O sui file
27 sono gestibili a basso livello con l'interfaccia standard unix, che ricorre
28 direttamente alle \textit{system call} messe a disposizione dal kernel.
30 Questa interfaccia però non provvede le funzionalità previste dallo standard
31 ANSI C, che invece sono realizzate attraverso opportune funzioni di libreria,
32 queste, insieme alle altre funzioni definite dallo standard, vengono a
33 costituire il nucleo\footnote{queste funzioni sono state implementate la prima
34 volta da Ritchie nel 1976 e da allora sono rimaste sostanzialmente
35 immutate.} delle \acr{glibc}.
38 \subsection{I \textit{file stream}}
39 \label{sec:file_stream}
41 \itindbeg{file~stream}
43 Come più volte ribadito, l'interfaccia dei file descriptor è un'interfaccia di
44 basso livello, che non provvede nessuna forma di formattazione dei dati e
45 nessuna forma di bufferizzazione per ottimizzare le operazioni di I/O.
47 In \cite{APUE} Stevens descrive una serie di test sull'influenza delle
48 dimensioni del blocco di dati (l'argomento \param{buf} di \func{read} e
49 \func{write}) nell'efficienza nelle operazioni di I/O con i file descriptor,
50 evidenziando come le prestazioni ottimali si ottengano a partire da dimensioni
51 del buffer dei dati pari a quelle dei blocchi del filesystem (il valore dato
52 dal campo \var{st\_blksize} di \struct{stat}), che di norma corrispondono alle
53 dimensioni dei settori fisici in cui è suddiviso il disco.
55 Se il programmatore non si cura di effettuare le operazioni in blocchi di
56 dimensioni adeguate, le prestazioni sono inferiori. La caratteristica
57 principale dell'interfaccia degli \textit{stream} è che essa provvede da sola
58 alla gestione dei dettagli della bufferizzazione e all'esecuzione delle
59 operazioni di lettura e scrittura in blocchi di dimensioni appropriate
60 all'ottenimento della massima efficienza.
62 Per questo motivo l'interfaccia viene chiamata anche interfaccia dei
63 \textit{file stream}, dato che non è più necessario doversi preoccupare
64 dei dettagli della comunicazione con il tipo di hardware sottostante
65 (come nel caso della dimensione dei blocchi del filesystem), ed un file
66 può essere sempre considerato come composto da un flusso continuo (da
67 cui il nome \textit{stream}) di dati.
69 A parte i dettagli legati alla gestione delle operazioni di lettura e
70 scrittura (sia per quel che riguarda la bufferizzazione, che le
71 formattazioni), i \textit{file stream} restano del tutto equivalenti ai file
72 descriptor (sui quali sono basati), ed in particolare continua a valere quanto
73 visto in sez.~\ref{sec:file_sharing} a proposito dell'accesso condiviso ed in
74 sez.~\ref{sec:file_access_control} per il controllo di accesso.
76 \itindend{file~stream}
79 \subsection{Gli oggetti \type{FILE}}
83 Per ragioni storiche la struttura di dati che rappresenta uno \textit{stream}
84 è stata chiamata \type{FILE}, questi oggetti sono creati dalle funzioni di
85 libreria e contengono tutte le informazioni necessarie a gestire le operazioni
86 sugli \textit{stream}, come la posizione corrente, lo stato del buffer e degli
87 indicatori di stato e di fine del file.
89 Per questo motivo gli utenti non devono mai utilizzare direttamente o allocare
90 queste strutture (che sono dei \index{tipo!opaco} \textsl{tipi opachi}) ma
91 usare sempre puntatori del tipo \texttt{FILE *} ottenuti dalla libreria stessa
92 (tanto che in certi casi il termine di puntatore a file è diventato sinonimo
93 di \textit{stream}). Tutte le funzioni della libreria che operano sui file
94 accettano come argomenti solo variabili di questo tipo, che diventa
95 accessibile includendo l'header file \headfile{stdio.h}.
98 \subsection{Gli \textit{stream standard}}
99 \label{sec:file_std_stream}
101 Ai tre file descriptor standard (vedi sez.~\ref{sec:file_std_descr}) aperti
102 per ogni processo, corrispondono altrettanti \textit{stream}, che
103 rappresentano i canali standard di input/output prestabiliti; anche questi tre
104 \textit{stream} sono identificabili attraverso dei nomi simbolici definiti
105 nell'header \headfile{stdio.h} che sono:
107 \begin{basedescript}{\desclabelwidth{3.0cm}}
108 \item[\var{FILE *stdin}] Lo \textit{standard input} cioè il \textit{file
109 stream} da cui il processo riceve ordinariamente i dati in
110 ingresso. Normalmente è associato dalla shell all'input del terminale e
111 prende i caratteri dalla tastiera.
112 \item[\var{FILE *stdout}] Lo \textit{standard output} cioè il \textit{file
113 stream} su cui il processo invia ordinariamente i dati in
114 uscita. Normalmente è associato dalla shell all'output del terminale e
115 scrive sullo schermo.
116 \item[\var{FILE *stderr}] Lo \textit{standard error} cioè il \textit{file
117 stream} su cui il processo è supposto inviare i messaggi di
118 errore. Normalmente anch'esso è associato dalla shell all'output del
119 terminale e scrive sullo schermo.
122 Nella \acr{glibc} \var{stdin}, \var{stdout} e \var{stderr} sono effettivamente
123 tre variabili di tipo \type{FILE}\texttt{ *} che possono essere usate come
124 tutte le altre, ad esempio si può effettuare una redirezione dell'output di un
125 programma con il semplice codice: \includecodesnip{listati/redir_stdout.c} ma
126 in altri sistemi queste variabili possono essere definite da macro, e se si
127 hanno problemi di portabilità e si vuole essere sicuri, diventa opportuno
128 usare la funzione \func{freopen}.
131 \subsection{Le modalità di bufferizzazione}
132 \label{sec:file_buffering}
134 La bufferizzazione è una delle caratteristiche principali dell'interfaccia
135 degli \textit{stream}; lo scopo è quello di ridurre al minimo il numero di
136 system call (\func{read} o \func{write}) eseguite nelle operazioni di
137 input/output. Questa funzionalità è assicurata automaticamente dalla libreria,
138 ma costituisce anche uno degli aspetti più comunemente fraintesi, in
139 particolare per quello che riguarda l'aspetto della scrittura dei dati sul
142 I caratteri che vengono scritti su di uno \textit{stream} normalmente vengono
143 accumulati in un buffer e poi trasmessi in blocco\footnote{questa operazione
144 viene usualmente chiamata \textsl{scaricamento} dei dati, dal termine
145 inglese \textit{flush}.} tutte le volte che il buffer viene riempito, in
146 maniera asincrona rispetto alla scrittura. Un comportamento analogo avviene
147 anche in lettura (cioè dal file viene letto un blocco di dati, anche se ne
148 sono richiesti una quantità inferiore), ma la cosa ovviamente ha rilevanza
149 inferiore, dato che i dati letti sono sempre gli stessi. In caso di scrittura
150 invece, quando si ha un accesso contemporaneo allo stesso file (ad esempio da
151 parte di un altro processo) si potranno vedere solo le parti effettivamente
152 scritte, e non quelle ancora presenti nel buffer.
154 Per lo stesso motivo, in tutte le situazioni in cui si sta facendo
155 dell'input/output interattivo, bisognerà tenere presente le caratteristiche
156 delle operazioni di scaricamento dei dati, poiché non è detto che ad una
157 scrittura sullo \textit{stream} corrisponda una immediata scrittura sul
158 dispositivo (la cosa è particolarmente evidente quando con le operazioni di
159 input/output su terminale).
161 Per rispondere ad esigenze diverse, lo standard definisce tre distinte
162 modalità in cui può essere eseguita la bufferizzazione, delle quali
163 occorre essere ben consapevoli, specie in caso di lettura e scrittura da
164 dispositivi interattivi:
166 \item \textit{unbuffered}: in questo caso non c'è bufferizzazione ed i
167 caratteri vengono trasmessi direttamente al file non appena possibile
168 (effettuando immediatamente una \func{write}).
169 \item \textit{line buffered}: in questo caso i caratteri vengono
170 normalmente trasmessi al file in blocco ogni volta che viene
171 incontrato un carattere di \textit{newline} (il carattere ASCII
173 \item \textit{fully buffered}: in questo caso i caratteri vengono
174 trasmessi da e verso il file in blocchi di dimensione opportuna.
177 Lo standard ANSI C specifica inoltre che lo standard output e lo
178 standard input siano aperti in modalità \textit{fully buffered} quando
179 non fanno riferimento ad un dispositivo interattivo, e che lo standard
180 error non sia mai aperto in modalità \textit{fully buffered}.
182 Linux, come BSD e SVr4, specifica il comportamento predefinito in maniera
183 ancora più precisa, e cioè impone che lo standard error sia sempre
184 \textit{unbuffered} (in modo che i messaggi di errore siano mostrati il più
185 rapidamente possibile) e che standard input e standard output siano aperti in
186 modalità \textit{line buffered} quando sono associati ad un terminale (od
187 altro dispositivo interattivo) ed in modalità \textit{fully buffered}
190 Il comportamento specificato per standard input e standard output vale anche
191 per tutti i nuovi \textit{stream} aperti da un processo; la selezione comunque
192 avviene automaticamente, e la libreria apre lo \textit{stream} nella modalità
193 più opportuna a seconda del file o del dispositivo scelto.
195 La modalità \textit{line buffered} è quella che necessita di maggiori
196 chiarimenti e attenzioni per quel che concerne il suo funzionamento. Come già
197 accennato nella descrizione, \emph{di norma} i dati vengono inviati al kernel
198 alla ricezione di un carattere di \textsl{a capo} (\textit{newline}); questo
199 non è vero in tutti i casi, infatti, dato che le dimensioni del buffer usato
200 dalle librerie sono fisse, se le si eccedono si può avere uno scarico dei dati
201 anche prima che sia stato inviato un carattere di \textit{newline}.
203 Un secondo punto da tenere presente, particolarmente quando si ha a che fare
204 con I/O interattivo, è che quando si effettua una lettura da uno
205 \textit{stream} che comporta l'accesso al kernel\footnote{questo vuol dire che
206 lo \textit{stream} da cui si legge è in modalità \textit{unbuffered}.} viene
207 anche eseguito lo scarico di tutti i buffer degli \textit{stream} in
210 In sez.~\ref{sec:file_buffering_ctrl} vedremo come la libreria definisca delle
211 opportune funzioni per controllare le modalità di bufferizzazione e lo scarico
216 \section{Funzioni base}
217 \label{sec:file_ansi_base_func}
219 Esamineremo in questa sezione le funzioni base dell'interfaccia degli
220 \textit{stream}, analoghe a quelle di sez.~\ref{sec:file_base_func} per i file
221 descriptor. In particolare vedremo come aprire, leggere, scrivere e cambiare
222 la posizione corrente in uno \textit{stream}.
225 \subsection{Apertura e chiusura di uno \textit{stream}}
226 \label{sec:file_fopen}
228 Le funzioni che si possono usare per aprire uno \textit{stream} sono solo tre:
229 \funcd{fopen}, \funcd{fdopen} e \funcd{freopen},\footnote{\func{fopen} e
230 \func{freopen} fanno parte dello standard ANSI C, \func{fdopen} è parte
231 dello standard POSIX.1.} i loro prototipi sono:
234 \funcdecl{FILE *fopen(const char *path, const char *mode)}
235 Apre il file specificato da \param{path}.
236 \funcdecl{FILE *fdopen(int fildes, const char *mode)}
237 Associa uno \textit{stream} al file descriptor \param{fildes}.
238 \funcdecl{FILE *freopen(const char *path, const char *mode, FILE *stream)}
239 Apre il file specificato da \param{path} associandolo allo \textit{stream}
240 specificato da \param{stream}, se questo è già aperto prima lo chiude.
242 \bodydesc{Le funzioni ritornano un puntatore valido in caso di successo e
243 \val{NULL} in caso di errore, in tal caso \var{errno} assumerà il valore
244 ricevuto dalla funzione sottostante di cui è fallita l'esecuzione.
246 Gli errori pertanto possono essere quelli di \func{malloc} per tutte
247 e tre le funzioni, quelli \func{open} per \func{fopen}, quelli di
248 \func{fcntl} per \func{fdopen} e quelli di \func{fopen},
249 \func{fclose} e \func{fflush} per \func{freopen}.}
252 Normalmente la funzione che si usa per aprire uno \textit{stream} è
253 \func{fopen}, essa apre il file specificato nella modalità specificata da
254 \param{mode}, che è una stringa che deve iniziare con almeno uno dei valori
255 indicati in tab.~\ref{tab:file_fopen_mode} (sono possibili varie estensioni
256 che vedremo in seguito).
258 L'uso più comune di \func{freopen} è per redirigere uno dei tre file
259 standard (vedi sez.~\ref{sec:file_std_stream}): il file \param{path} viene
260 associato a \param{stream} e se questo è uno \textit{stream} già aperto viene
261 preventivamente chiuso.
263 Infine \func{fdopen} viene usata per associare uno \textit{stream} ad un file
264 descriptor esistente ottenuto tramite una altra funzione (ad esempio con una
265 \func{open}, una \func{dup}, o una \func{pipe}) e serve quando si vogliono
266 usare gli \textit{stream} con file come le fifo o i socket, che non possono
267 essere aperti con le funzioni delle librerie standard del C.
272 \begin{tabular}[c]{|l|p{8cm}|}
274 \textbf{Valore} & \textbf{Significato}\\
277 \texttt{r} & Il file viene aperto, l'accesso viene posto in sola
278 lettura, lo \textit{stream} è posizionato all'inizio del
280 \texttt{r+}& Il file viene aperto, l'accesso viene posto in lettura e
281 scrittura, lo \textit{stream} è posizionato all'inizio del
284 \texttt{w} & Il file viene aperto e troncato a lunghezza nulla (o
285 creato se non esiste), l'accesso viene posto in sola
286 scrittura, lo stream\textit{} è posizionato all'inizio del
288 \texttt{w+}& Il file viene aperto e troncato a lunghezza nulla (o
289 creato se non esiste), l'accesso viene posto in scrittura e
290 lettura, lo \textit{stream} è posizionato all'inizio del
293 \texttt{a} & Il file viene aperto (o creato se non esiste) in
294 \itindex{append~mode} \textit{append mode}, l'accesso viene
295 posto in sola scrittura.\\
296 \texttt{a+}& Il file viene aperto (o creato se non esiste) in
297 \itindex{append~mode} \textit{append mode}, l'accesso viene
298 posto in lettura e scrittura.\\
300 \texttt{b} & Specifica che il file è binario, non ha alcun effetto. \\
301 \texttt{x} & L'apertura fallisce se il file esiste già. \\
304 \caption{Modalità di apertura di uno \textit{stream} dello standard ANSI C
305 che sono sempre presenti in qualunque sistema POSIX.}
306 \label{tab:file_fopen_mode}
309 In realtà lo standard ANSI C prevede un totale di 15 possibili valori
310 diversi per \param{mode}, ma in tab.~\ref{tab:file_fopen_mode} si sono
311 riportati solo i sei valori effettivi, ad essi può essere aggiunto pure
312 il carattere \texttt{b} (come ultimo carattere o nel mezzo agli altri per
313 le stringhe di due caratteri) che in altri sistemi operativi serve a
314 distinguere i file binari dai file di testo; in un sistema POSIX questa
315 distinzione non esiste e il valore viene accettato solo per
316 compatibilità, ma non ha alcun effetto.
318 Le \acr{glibc} supportano alcune estensioni, queste devono essere sempre
319 indicate dopo aver specificato il \param{mode} con uno dei valori di
320 tab.~\ref{tab:file_fopen_mode}. L'uso del carattere \texttt{x} serve per
321 evitare di sovrascrivere un file già esistente (è analoga all'uso
322 dell'opzione \const{O\_EXCL} in \func{open}), se il file specificato già
323 esiste e si aggiunge questo carattere a \param{mode} la \func{fopen}
326 Un'altra estensione serve a supportare la localizzazione, quando si
327 aggiunge a \param{mode} una stringa della forma \verb|",ccs=STRING"| il
328 valore \verb|STRING| è considerato il nome di una codifica dei caratteri
329 e \func{fopen} marca il file per l'uso dei caratteri estesi e abilita le
330 opportune funzioni di conversione in lettura e scrittura.
332 Nel caso si usi \func{fdopen} i valori specificati da \param{mode} devono
333 essere compatibili con quelli con cui il file descriptor è stato aperto.
334 Inoltre i modi \cmd{w} e \cmd{w+} non troncano il file. La posizione nello
335 \textit{stream} viene impostata a quella corrente nel file descriptor, e le
336 variabili di errore e di fine del file (vedi sez.~\ref{sec:file_io}) sono
337 cancellate. Il file non viene duplicato e verrà chiuso alla chiusura dello
340 I nuovi file saranno creati secondo quanto visto in
341 sez.~\ref{sec:file_ownership_management} ed avranno i permessi di accesso
343 \code{S\_IRUSR|S\_IWUSR|S\_IRGRP|S\_IWGRP|S\_IROTH|S\_IWOTH} (pari a
344 \val{0666}) modificato secondo il valore di \itindex{umask} \textit{umask} per
345 il processo (si veda sez.~\ref{sec:file_perm_management}).
347 In caso di file aperti in lettura e scrittura occorre ricordarsi che c'è
348 di mezzo una bufferizzazione; per questo motivo lo standard ANSI C
349 richiede che ci sia un'operazione di posizionamento fra un'operazione
350 di output ed una di input o viceversa (eccetto il caso in cui l'input ha
351 incontrato la fine del file), altrimenti una lettura può ritornare anche
352 il risultato di scritture precedenti l'ultima effettuata.
354 Per questo motivo è una buona pratica (e talvolta necessario) far seguire ad
355 una scrittura una delle funzioni \func{fflush}, \func{fseek}, \func{fsetpos} o
356 \func{rewind} prima di eseguire una rilettura; viceversa nel caso in cui si
357 voglia fare una scrittura subito dopo aver eseguito una lettura occorre prima
358 usare una delle funzioni \func{fseek}, \func{fsetpos} o \func{rewind}. Anche
359 un'operazione nominalmente nulla come \code{fseek(file, 0, SEEK\_CUR)} è
360 sufficiente a garantire la sincronizzazione.
362 Una volta aperto lo \textit{stream}, si può cambiare la modalità di
363 bufferizzazione (si veda sez.~\ref{sec:file_buffering_ctrl}) fintanto che non
364 si è effettuato alcuna operazione di I/O sul file.
366 Uno \textit{stream} viene chiuso con la funzione \funcd{fclose} il cui
368 \begin{prototype}{stdio.h}{int fclose(FILE *stream)}
369 Chiude lo \textit{stream} \param{stream}.
371 \bodydesc{Restituisce 0 in caso di successo e \val{EOF} in caso di errore,
372 nel qual caso imposta \var{errno} a \errval{EBADF} se il file descriptor
373 indicato da \param{stream} non è valido, o uno dei valori specificati
374 dalla sottostante funzione che è fallita (\func{close}, \func{write} o
378 La funzione effettua lo scarico di tutti i dati presenti nei buffer di uscita
379 e scarta tutti i dati in ingresso; se era stato allocato un buffer per lo
380 \textit{stream} questo verrà rilasciato. La funzione effettua lo scarico solo
381 per i dati presenti nei buffer in user space usati dalle \acr{glibc}; se si
382 vuole essere sicuri che il kernel forzi la scrittura su disco occorrerà
383 effettuare una \func{sync} (vedi sez.~\ref{sec:file_sync}).
385 Linux supporta anche una altra funzione, \funcd{fcloseall}, come estensione
386 GNU implementata dalle \acr{glibc}, accessibile avendo definito
387 \macro{\_GNU\_SOURCE}, il suo prototipo è:
388 \begin{prototype}{stdio.h}{int fcloseall(void)}
389 Chiude tutti gli \textit{stream}.
391 \bodydesc{Restituisce 0 se non ci sono errori ed \val{EOF} altrimenti.}
393 \noindent la funzione esegue lo scarico dei dati bufferizzati in uscita
394 e scarta quelli in ingresso, chiudendo tutti i file. Questa funzione è
395 provvista solo per i casi di emergenza, quando si è verificato un errore
396 ed il programma deve essere abortito, ma si vuole compiere qualche altra
397 operazione dopo aver chiuso i file e prima di uscire (si ricordi quanto
398 visto in sez.~\ref{sec:proc_conclusion}).
401 \subsection{Lettura e scrittura su uno \textit{stream}}
404 Una delle caratteristiche più utili dell'interfaccia degli \textit{stream} è
405 la ricchezza delle funzioni disponibili per le operazioni di lettura e
406 scrittura sui file. Sono infatti previste ben tre diverse modalità modalità di
407 input/output non formattato:
409 \item\textsl{binario} in cui legge/scrive un blocco di dati alla
410 volta, vedi sez.~\ref{sec:file_binary_io}.
411 \item\textsl{a caratteri} in cui si legge/scrive un carattere alla
412 volta (con la bufferizzazione gestita automaticamente dalla libreria),
413 vedi sez.~\ref{sec:file_char_io}.
414 \item\textsl{di linea} in cui si legge/scrive una linea alla volta (terminata
415 dal carattere di newline \verb|'\n'|), vedi sez.~\ref{sec:file_line_io}.
417 ed inoltre la modalità di input/output formattato.
419 A differenza dell'interfaccia dei file descriptor, con gli \textit{stream} il
420 raggiungimento della fine del file è considerato un errore, e viene
421 notificato come tale dai valori di uscita delle varie funzioni. Nella
422 maggior parte dei casi questo avviene con la restituzione del valore
423 intero (di tipo \ctyp{int}) \val{EOF}\footnote{la costante deve essere
424 negativa, le \acr{glibc} usano -1, altre implementazioni possono avere
425 valori diversi.} definito anch'esso nell'header \headfile{stdlib.h}.
427 Dato che le funzioni dell'interfaccia degli \textit{stream} sono funzioni di
428 libreria che si appoggiano a delle system call, esse non impostano
429 direttamente la variabile \var{errno}, che mantiene il valore impostato dalla
430 system call che ha riportato l'errore.
432 Siccome la condizione di end-of-file è anch'essa segnalata come errore, nasce
433 il problema di come distinguerla da un errore effettivo; basarsi solo sul
434 valore di ritorno della funzione e controllare il valore di \var{errno}
435 infatti non basta, dato che quest'ultimo potrebbe essere stato impostato in
436 una altra occasione, (si veda sez.~\ref{sec:sys_errno} per i dettagli del
437 funzionamento di \var{errno}).
439 Per questo motivo tutte le implementazioni delle librerie standard mantengono
440 per ogni \textit{stream} almeno due flag all'interno dell'oggetto \type{FILE},
441 il flag di \textit{end-of-file}, che segnala che si è raggiunta la fine del
442 file in lettura, e quello di errore, che segnala la presenza di un qualche
443 errore nelle operazioni di input/output; questi due flag possono essere
444 riletti dalle funzioni \funcd{feof} e \funcd{ferror}, i cui prototipi sono:
447 \funcdecl{int feof(FILE *stream)}
448 Controlla il flag di end-of-file di \param{stream}.
449 \funcdecl{int ferror(FILE *stream)}
450 Controlla il flag di errore di \param{stream}.
452 \bodydesc{Entrambe le funzioni ritornano un valore diverso da zero se
453 i relativi flag sono impostati.}
455 \noindent si tenga presente comunque che la lettura di questi flag segnala
456 soltanto che c'è stato un errore, o che si è raggiunta la fine del file in una
457 qualunque operazione sullo \textit{stream}, il controllo quindi deve essere
458 effettuato ogni volta che si chiama una funzione di libreria.
460 Entrambi i flag (di errore e di end-of-file) possono essere cancellati usando
461 la funzione \funcd{clearerr}, il cui prototipo è:
462 \begin{prototype}{stdio.h}{void clearerr(FILE *stream)}
463 Cancella i flag di errore ed \textit{end-of-file} di \param{stream}.
465 \noindent in genere si usa questa funzione una volta che si sia identificata e
466 corretta la causa di un errore per evitare di mantenere i flag attivi, così da
467 poter rilevare una successiva ulteriore condizione di errore. Di questa
468 funzione esiste una analoga \funcm{clearerr\_unlocked} che non esegue il
469 blocco dello \textit{stream} (vedi sez.~\ref{sec:file_stream_thread}).
472 \subsection{Input/output binario}
473 \label{sec:file_binary_io}
475 La prima modalità di input/output non formattato ricalca quella della
476 interfaccia dei file descriptor, e provvede semplicemente la scrittura e la
477 lettura dei dati da un buffer verso un file e viceversa. In generale questa è
478 la modalità che si usa quando si ha a che fare con dati non formattati. Le due
479 funzioni che si usano per l'I/O binario sono \funcd{fread} ed \funcd{fwrite};
480 i loro prototipi sono:
484 \funcdecl{size\_t fread(void *ptr, size\_t size, size\_t nmemb, FILE
487 \funcdecl{size\_t fwrite(const void *ptr, size\_t size, size\_t
488 nmemb, FILE *stream)}
490 Rispettivamente leggono e scrivono \param{nmemb} elementi di dimensione
491 \param{size} dal buffer \param{ptr} al file \param{stream}.
493 \bodydesc{Entrambe le funzioni ritornano il numero di elementi letti o
494 scritti, in caso di errore o fine del file viene restituito un numero di
495 elementi inferiore al richiesto.}
498 In genere si usano queste funzioni quando si devono trasferire su file
499 blocchi di dati binari in maniera compatta e veloce; un primo caso di uso
500 tipico è quello in cui si salva un vettore (o un certo numero dei suoi
501 elementi) con una chiamata del tipo:
502 \includecodesnip{listati/WriteVect.c}
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 \includecodesnip{listati/WriteStruct.c}
508 in cui si specifica la dimensione dell'intera struttura ed un solo
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.
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 (lo
518 stesso avviene in caso di errore). In questo caso la posizione dello
519 \textit{stream} viene impostata alla fine del file (e non a quella
520 corrispondente alla quantità di dati letti).
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
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.
535 Infatti diversi compilatori possono eseguire ottimizzazioni diverse delle
536 strutture dati e alcuni compilatori (come il \cmd{gcc}) possono anche
537 scegliere se ottimizzare l'occupazione di spazio, impacchettando più
538 strettamente i dati, o la velocità inserendo opportuni \textit{padding} per
539 l'allineamento dei medesimi generando quindi output binari diversi. Inoltre
540 altre incompatibilità si possono presentare quando entrano in gioco differenze
541 di architettura hardware, come la dimensione del bus o la modalità di
542 ordinamento dei bit o il formato delle variabili in floating point.
544 Per questo motivo quando si usa l'input/output binario occorre sempre prendere
545 le opportune precauzioni (in genere usare un formato di più alto livello che
546 permetta di recuperare l'informazione completa), per assicurarsi che versioni
547 diverse del programma siano in grado di rileggere i dati tenendo conto delle
548 eventuali differenze.
550 Le \acr{glibc} definiscono altre due funzioni per l'I/O binario,
551 \funcd{fread\_unlocked} e \funcd{fwrite\_unlocked} che evitano il lock
552 implicito dello \textit{stream}, usato per dalla librerie per la gestione delle
553 applicazioni \itindex{thread} \textit{multi-thread} (si veda
554 sez.~\ref{sec:file_stream_thread} per i dettagli), i loro prototipi sono:
558 \funcdecl{size\_t fread\_unlocked(void *ptr, size\_t size, size\_t
559 nmemb, FILE *stream)}
561 \funcdecl{size\_t fwrite\_unlocked(const void *ptr, size\_t size,
562 size\_t nmemb, FILE *stream)}
564 \bodydesc{Le funzioni sono identiche alle analoghe \func{fread} e
565 \func{fwrite} ma non acquisiscono il lock implicito sullo \textit{stream}.}
567 \noindent entrambe le funzioni sono estensioni GNU previste solo dalle
571 \subsection{Input/output a caratteri}
572 \label{sec:file_char_io}
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, \funcd{fgetc}, \funcd{getc} e \funcd{getchar}, i
577 rispettivi prototipi sono:
581 \funcdecl{int getc(FILE *stream)} Legge un byte da \param{stream} e lo
582 restituisce come intero. In genere è implementata come una macro.
584 \funcdecl{int fgetc(FILE *stream)} Legge un byte da \param{stream} e lo
585 restituisce come intero. È sempre una funzione.
587 \funcdecl{int getchar(void)} Equivalente a \code{getc(stdin)}.
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 è \val{EOF}.}
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 sez.~\ref{sec:proc_var_passing}; per questo motivo se
601 si passa un'espressione si possono avere effetti indesiderati.
603 Invece \func{fgetc} è assicurata essere sempre una funzione, per questo motivo
604 la sua esecuzione normalmente è più lenta per via dell'overhead della
605 chiamata, ma è altresì possibile ricavarne l'indirizzo, che può essere passato
606 come argomento ad un altra funzione (e non si hanno i problemi accennati in
607 precedenza nel tipo di argomento).
609 Le tre funzioni restituiscono tutte un \ctyp{unsigned char} convertito
610 ad \ctyp{int} (si usa \ctyp{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.
614 Nelle estensioni GNU che provvedono la localizzazione sono definite tre
615 funzioni equivalenti alle precedenti, \funcd{getwc}, \funcd{fgetwc} e
616 \funcd{getwchar}, che invece di un carattere di un byte restituiscono un
617 carattere in formato esteso (cioè di tipo \ctyp{wint\_t}), il loro prototipo
623 \funcdecl{wint\_t getwc(FILE *stream)} Legge un carattere esteso da
624 \param{stream}. In genere è implementata come una macro.
626 \funcdecl{wint\_t fgetwc(FILE *stream)} Legge un carattere esteso da
627 \param{stream}. È una sempre una funzione.
629 \funcdecl{wint\_t getwchar(void)} Equivalente a \code{getwc(stdin)}.
631 \bodydesc{Tutte queste funzioni leggono un carattere alla volta, in
632 caso di errore o fine del file il valore di ritorno è \const{WEOF}.}
635 Per scrivere un carattere si possono usare tre funzioni, analoghe alle
636 precedenti usate per leggere: \funcd{putc}, \funcd{fputc} e \funcd{putchar}; i
641 \funcdecl{int putc(int c, FILE *stream)} Scrive il carattere \param{c}
642 su \param{stream}. In genere è implementata come una macro.
644 \funcdecl{int fputc(int c, FILE *stream)} Scrive il carattere \param{c} su
645 \param{stream}. È una sempre una funzione.
647 \funcdecl{int putchar(int c)} Equivalente a \code{putc(stdout)}.
649 \bodydesc{Le funzioni scrivono sempre un carattere alla volta, il cui
650 valore viene restituito in caso di successo; in caso di errore o
651 fine del file il valore di ritorno è \val{EOF}.}
654 Tutte queste funzioni scrivono sempre un byte alla volta, anche se prendono
655 come argomento un \ctyp{int} (che pertanto deve essere ottenuto con un cast da
656 un \ctyp{unsigned char}). Anche il valore di ritorno è sempre un intero; in
657 caso di errore o fine del file il valore di ritorno è \val{EOF}.
659 Come nel caso dell'I/O binario con \func{fread} e \func{fwrite} le \acr{glibc}
660 provvedono come estensione, per ciascuna delle funzioni precedenti,
661 un'ulteriore funzione, il cui nome è ottenuto aggiungendo un
662 \code{\_unlocked}, che esegue esattamente le stesse operazioni, evitando però
663 il lock implicito dello \textit{stream}.
665 Per compatibilità con SVID sono inoltre provviste anche due funzioni,
666 \funcd{getw} e \funcd{putw}, da usare per leggere e scrivere una \textit{word}
667 (cioè due byte in una volta); i loro prototipi sono:
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
675 \bodydesc{Le funzioni restituiscono la parola \param{w}, o \val{EOF}
676 in caso di errore o di fine del file.}
679 Le funzioni leggono e scrivono una \textit{word} di due byte, usando comunque
680 una variabile di tipo \ctyp{int}; il loro uso è deprecato in favore dell'uso
681 di \func{fread} e \func{fwrite}, in quanto non è possibile distinguere il
682 valore -1 da una condizione di errore che restituisce \val{EOF}.
684 Uno degli usi più frequenti dell'input/output a caratteri è nei programmi di
685 \textit{parsing} in cui si analizza il testo; in questo contesto diventa utile
686 poter analizzare il carattere successivo da uno \textit{stream} senza estrarlo
687 effettivamente (la tecnica è detta \textit{peeking ahead}) in modo che il
688 programma possa regolarsi avendo dato una \textsl{sbirciatina} a quello che
691 Nel nostro caso questo tipo di comportamento può essere realizzato prima
692 leggendo il carattere, e poi rimandandolo indietro, cosicché ridiventi
693 disponibile per una lettura successiva; la funzione che inverte la
694 lettura si chiama \funcd{ungetc} ed il suo prototipo è:
695 \begin{prototype}{stdio.h}{int ungetc(int c, FILE *stream)}
696 Rimanda indietro il carattere \param{c}, con un cast a \ctyp{unsigned
697 char}, sullo \textit{stream} \param{stream}.
699 \bodydesc{La funzione ritorna \param{c} in caso di successo e
700 \val{EOF} in caso di errore.}
702 \noindent benché lo standard ANSI C preveda che l'operazione possa
703 essere ripetuta per un numero arbitrario di caratteri, alle
704 implementazioni è richiesto di garantire solo un livello; questo è
705 quello che fa la \acr{glibc}, che richiede che avvenga un'altra
706 operazione fra due \func{ungetc} successive.
708 Non è necessario che il carattere che si manda indietro sia l'ultimo che
709 si è letto, e non è necessario neanche avere letto nessun carattere
710 prima di usare \func{ungetc}, ma di norma la funzione è intesa per
711 essere usata per rimandare indietro l'ultimo carattere letto.
713 Nel caso \param{c} sia un \val{EOF} la funzione non fa nulla, e
714 restituisce sempre \val{EOF}; così si può usare \func{ungetc} anche
715 con il risultato di una lettura alla fine del file.
717 Se si è alla fine del file si può comunque rimandare indietro un
718 carattere, il flag di end-of-file verrà automaticamente cancellato
719 perché c'è un nuovo carattere disponibile che potrà essere riletto
722 Infine si tenga presente che \func{ungetc} non altera il contenuto del
723 file, ma opera esclusivamente sul buffer interno. Se si esegue una
724 qualunque delle operazioni di riposizionamento (vedi
725 sez.~\ref{sec:file_fseek}) i caratteri rimandati indietro vengono
729 \subsection{Input/output di linea}
730 \label{sec:file_line_io}
732 La terza ed ultima modalità di input/output non formattato è quella di linea,
733 in cui si legge o si scrive una riga alla volta; questa è una modalità molto
734 usata per l'I/O da terminale, ma è anche quella che presenta le
735 caratteristiche più controverse.
737 Le funzioni previste dallo standard ANSI C per leggere una linea sono
738 sostanzialmente due, \funcd{gets} e \funcd{fgets}, i cui rispettivi
743 \funcdecl{char *gets(char *string)} Scrive su \param{string} una
744 linea letta da \var{stdin}.
746 \funcdecl{char *fgets(char *string, int size, FILE *stream)}
747 Scrive su \param{string} la linea letta da \param{stream} per un
748 massimo di \param{size} byte.
750 \bodydesc{Le funzioni restituiscono l'indirizzo \param{string} in caso
751 di successo o \val{NULL} in caso di errore.}
754 Entrambe le funzioni effettuano la lettura (dal file specificato \func{fgets},
755 dallo standard input \func{gets}) di una linea di caratteri (terminata dal
756 carattere \textit{newline}, \verb|'\n'|, quello mappato sul tasto di ritorno a
757 capo della tastiera), ma \func{gets} sostituisce \verb|'\n'| con uno zero,
758 mentre \func{fgets} aggiunge uno zero dopo il \textit{newline}, che resta
759 dentro la stringa. Se la lettura incontra la fine del file (o c'è un errore)
760 viene restituito un \val{NULL}, ed il buffer \param{buf} non viene toccato.
761 L'uso di \func{gets} è deprecato e deve essere assolutamente evitato; la
762 funzione infatti non controlla il numero di byte letti, per cui nel caso la
763 stringa letta superi le dimensioni del buffer, si avrà un
764 \itindex{buffer~overflow} \textit{buffer overflow}, con sovrascrittura della
765 memoria del processo adiacente al buffer.\footnote{questa tecnica è spiegata
766 in dettaglio e con molta efficacia nell'ormai famoso articolo di Aleph1
769 Questa è una delle vulnerabilità più sfruttate per guadagnare accessi non
770 autorizzati al sistema (i cosiddetti \textit{exploit}), basta infatti inviare
771 una stringa sufficientemente lunga ed opportunamente forgiata per
772 sovrascrivere gli indirizzi di ritorno nello \itindex{stack} \textit{stack}
773 (supposto che la \func{gets} sia stata chiamata da una subroutine), in modo da
774 far ripartire l'esecuzione nel codice inviato nella stringa stessa (in genere
775 uno \textit{shell code} cioè una sezione di programma che lancia una shell).
777 La funzione \func{fgets} non ha i precedenti problemi di \func{gets} in quanto
778 prende in input la dimensione del buffer \param{size}, che non verrà mai
779 ecceduta in lettura. La funzione legge fino ad un massimo di \param{size}
780 caratteri (newline compreso), ed aggiunge uno zero di terminazione; questo
781 comporta che la stringa possa essere al massimo di \code{size-1} caratteri. Se
782 la linea eccede la dimensione del buffer verranno letti solo \code{size-1}
783 caratteri, ma la stringa sarà sempre terminata correttamente con uno zero
784 finale; sarà possibile leggere i rimanenti caratteri in una chiamata
787 Per la scrittura di una linea lo standard ANSI C prevede altre due
788 funzioni, \funcd{fputs} e \funcd{puts}, analoghe a quelle di lettura, i
789 rispettivi prototipi sono:
793 \funcdecl{int puts(const char *string)} Scrive su \var{stdout} la
794 linea \param{string}.
796 \funcdecl{int fputs(const char *string, FILE *stream)} Scrive su
797 \param{stream} la linea \param{string}.
799 \bodydesc{Le funzioni restituiscono un valore non negativo in caso di
800 successo o \val{EOF} in caso di errore.}
803 Dato che in questo caso si scrivono i dati in uscita \func{puts} non ha i
804 problemi di \func{gets} ed è in genere la forma più immediata per scrivere
805 messaggi sullo standard output; la funzione prende una stringa terminata da
806 uno zero ed aggiunge automaticamente il ritorno a capo. La differenza con
807 \func{fputs} (a parte la possibilità di specificare un file diverso da
808 \var{stdout}) è che quest'ultima non aggiunge il newline, che deve essere
809 previsto esplicitamente.
811 Come per le analoghe funzioni di input/output a caratteri, anche per l'I/O di
812 linea esistono delle estensioni per leggere e scrivere linee di caratteri
813 estesi, le funzioni in questione sono \funcd{fgetws} e \funcd{fputws} ed i
817 \funcdecl{wchar\_t *fgetws(wchar\_t *ws, int n, FILE *stream)}
818 Legge un massimo di \param{n} caratteri estesi dal file
819 \param{stream} al buffer \param{ws}.
821 \funcdecl{int fputws(const wchar\_t *ws, FILE *stream)} Scrive la
822 linea \param{ws} di caratteri estesi sul file \param{stream}.
824 \bodydesc{Le funzioni ritornano rispettivamente \param{ws} o un numero
825 non negativo in caso di successo e \val{NULL} o \val{EOF} in
826 caso di errore o fine del file.}
829 Il comportamento di queste due funzioni è identico a quello di \func{fgets} e
830 \func{fputs}, a parte il fatto che tutto (numero di caratteri massimo,
831 terminatore della stringa, newline) è espresso in termini di caratteri estesi
832 anziché di normali caratteri ASCII.
834 Come per l'I/O binario e quello a caratteri, anche per l'I/O di linea le
835 \acr{glibc} supportano una serie di altre funzioni, estensioni di tutte quelle
836 illustrate finora (eccetto \func{gets} e \func{puts}), che eseguono
837 esattamente le stesse operazioni delle loro equivalenti, evitando però il lock
838 implicito dello \textit{stream} (vedi sez.~\ref{sec:file_stream_thread}). Come
839 per le altre forma di I/O, dette funzioni hanno lo stesso nome della loro
840 analoga normale, con l'aggiunta dell'estensione \code{\_unlocked}.
842 Come abbiamo visto, le funzioni di lettura per l'input/output di linea
843 previste dallo standard ANSI C presentano svariati inconvenienti. Benché
844 \func{fgets} non abbia i gravissimi problemi di \func{gets}, può
845 comunque dare risultati ambigui se l'input contiene degli zeri; questi
846 infatti saranno scritti sul buffer di uscita e la stringa in output
847 apparirà come più corta dei byte effettivamente letti. Questa è una
848 condizione che è sempre possibile controllare (deve essere presente un
849 newline prima della effettiva conclusione della stringa presente nel
850 buffer), ma a costo di una complicazione ulteriore della logica del
851 programma. Lo stesso dicasi quando si deve gestire il caso di stringa
852 che eccede le dimensioni del buffer.
854 Per questo motivo le \acr{glibc} prevedono, come estensione GNU, due nuove
855 funzioni per la gestione dell'input/output di linea, il cui uso permette di
856 risolvere questi problemi. L'uso di queste funzioni deve essere attivato
857 definendo la macro \macro{\_GNU\_SOURCE} prima di includere
858 \headfile{stdio.h}. La prima delle due, \funcd{getline}, serve per leggere una
859 linea terminata da un newline, esattamente allo stesso modo di \func{fgets},
861 \begin{prototype}{stdio.h}
862 {ssize\_t getline(char **buffer, size\_t *n, FILE *stream)} Legge una linea
863 dal file \param{stream} copiandola sul buffer indicato da \param{buffer}
864 riallocandolo se necessario (l'indirizzo del buffer e la sua dimensione
865 vengono sempre riscritte).
867 \bodydesc{La funzione ritorna il numero di caratteri letti in caso di
868 successo e -1 in caso di errore o di raggiungimento della fine del
872 La funzione permette di eseguire una lettura senza doversi preoccupare della
873 eventuale lunghezza eccessiva della stringa da leggere. Essa prende come primo
874 argomento l'indirizzo del puntatore al buffer su cui si vuole copiare la
875 linea. Quest'ultimo \emph{deve} essere stato allocato in precedenza con una
876 \func{malloc} (non si può passare l'indirizzo di un puntatore ad una variabile
877 locale); come secondo argomento la funzione vuole l'indirizzo della variabile
878 contenente le dimensioni del buffer suddetto.
880 Se il buffer di destinazione è sufficientemente ampio la stringa viene scritta
881 subito, altrimenti il buffer viene allargato usando \func{realloc} e la nuova
882 dimensione ed il nuovo puntatore vengono restituiti indietro (si noti infatti
883 come per entrambi gli argomenti si siano usati dei
884 \itindex{value~result~argument} \textit{value result argument}, passando dei
885 puntatori anziché i valori delle variabili, secondo la tecnica spiegata in
886 sez.~\ref{sec:proc_var_passing}).
888 Se si passa alla funzione l'indirizzo di un puntatore impostato a \val{NULL} e
889 \var{*n} è zero, la funzione provvede da sola all'allocazione della memoria
890 necessaria a contenere la linea. In tutti i casi si ottiene dalla funzione un
891 puntatore all'inizio del testo della linea letta. Un esempio di codice può
893 \includecodesnip{listati/getline.c}
894 e per evitare \itindex{memory~leak} \textit{memory leak} occorre ricordarsi di
895 liberare \var{ptr} con una \func{free}.
897 Il valore di ritorno della funzione indica il numero di caratteri letti
898 dallo \textit{stream} (quindi compreso il newline, ma non lo zero di
899 terminazione); questo permette anche di distinguere eventuali zeri letti
900 dallo \textit{stream} da quello inserito dalla funzione per terminare la linea.
901 Se si è alla fine del file e non si è potuto leggere nulla o c'è stato
902 un errore la funzione restituisce -1.
904 La seconda estensione GNU è una generalizzazione di \func{getline} per
905 poter usare come separatore un carattere qualsiasi, la funzione si
906 chiama \funcd{getdelim} ed il suo prototipo è:
907 \begin{prototype}{stdio.h}
908 {ssize\_t getdelim(char **buffer, size\_t *n, int delim, FILE *stream)}
909 Identica a \func{getline} solo che usa \param{delim} al posto del
910 carattere di newline come separatore di linea.
913 Il comportamento di \func{getdelim} è identico a quello di \func{getline} (che
914 può essere implementata da questa passando \verb|'\n'| come valore di
918 \subsection{L'input/output formattato}
919 \label{sec:file_formatted_io}
921 L'ultima modalità di input/output è quella formattata, che è una delle
922 caratteristiche più utilizzate delle librerie standard del C; in genere questa
923 è la modalità in cui si esegue normalmente l'output su terminale poiché
924 permette di stampare in maniera facile e veloce dati, tabelle e messaggi.
926 L'output formattato viene eseguito con una delle 13 funzioni della famiglia
927 \func{printf}; le tre più usate sono \funcd{printf}, \funcd{fprintf} e
928 \funcd{sprintf}, i cui prototipi sono:
931 \funcdecl{int printf(const char *format, ...)} Stampa su \file{stdout}
932 gli argomenti, secondo il formato specificato da \param{format}.
934 \funcdecl{int fprintf(FILE *stream, const char *format, ...)} Stampa
935 su \param{stream} gli argomenti, secondo il formato specificato da
938 \funcdecl{int sprintf(char *str, const char *format, ...)} Stampa
939 sulla stringa \param{str} gli argomenti, secondo il formato
940 specificato da \param{format}.
942 \bodydesc{Le funzioni ritornano il numero di caratteri stampati.}
944 \noindent le prime due servono per stampare su file (lo standard output o
945 quello specificato) la terza permette di stampare su una stringa, in genere
946 l'uso di \func{sprintf} è sconsigliato in quanto è possibile, se non si ha la
947 sicurezza assoluta sulle dimensioni del risultato della stampa, eccedere le
948 dimensioni di \param{str}, con conseguente sovrascrittura di altre variabili e
949 possibili \itindex{buffer~overflow} \textit{buffer overflow}; per questo
950 motivo si consiglia l'uso dell'alternativa \funcd{snprintf}, il cui prototipo
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.
958 La parte più complessa delle funzioni di scrittura formattata è il formato
959 della stringa \param{format} che indica le conversioni da fare, e da cui
960 deriva anche il numero degli argomenti che dovranno essere passati a seguire
961 (si noti come tutte queste funzioni siano \index{funzioni!variadic}
962 \textit{variadic}, prendendo un numero di argomenti variabile che dipende
963 appunto da quello che si è specificato in \param{format}).
968 \begin{tabular}[c]{|l|l|p{10cm}|}
970 \textbf{Valore} & \textbf{Tipo} & \textbf{Significato} \\
973 \cmd{\%d} &\ctyp{int} & Stampa un numero intero in formato decimale
975 \cmd{\%i} &\ctyp{int} & Identico a \cmd{\%i} in output.\\
976 \cmd{\%o} &\ctyp{unsigned int}& Stampa un numero intero come ottale.\\
977 \cmd{\%u} &\ctyp{unsigned int}& Stampa un numero intero in formato
978 decimale senza segno.\\
980 \cmd{\%X} &\ctyp{unsigned int}& Stampano un intero in formato esadecimale,
981 rispettivamente con lettere minuscole e
983 \cmd{\%f} &\ctyp{double} & Stampa un numero in virgola mobile con la
984 notazione a virgola fissa.\\
986 \cmd{\%E} &\ctyp{double} & Stampano un numero in virgola mobile con la
987 notazione esponenziale, rispettivamente con
988 lettere minuscole e maiuscole.\\
990 \cmd{\%G} &\ctyp{double} & Stampano un numero in virgola mobile con la
991 notazione più appropriate delle due precedenti,
992 rispettivamente con lettere minuscole e
995 \cmd{\%A} &\ctyp{double} & Stampano un numero in virgola mobile in
996 notazione esadecimale frazionaria.\\
997 \cmd{\%c} &\ctyp{int} & Stampa un carattere singolo.\\
998 \cmd{\%s} &\ctyp{char *} & Stampa una stringa.\\
999 \cmd{\%p} &\ctyp{void *} & Stampa il valore di un puntatore.\\
1000 \cmd{\%n} &\ctyp{\&int} & Prende il numero di caratteri stampati finora.\\
1001 \cmd{\%\%}& & Stampa un \%.\\
1004 \caption{Valori possibili per gli specificatori di conversione in una
1005 stringa di formato di \func{printf}.}
1006 \label{tab:file_format_spec}
1009 La stringa è costituita da caratteri normali (tutti eccetto \texttt{\%}), che
1010 vengono passati invariati all'output, e da direttive di conversione, in cui
1011 devono essere sempre presenti il carattere \texttt{\%}, che introduce la
1012 direttiva, ed uno degli specificatori di conversione (riportati in
1013 tab.~\ref{tab:file_format_spec}) che la conclude.
1018 \begin{tabular}[c]{|l|p{10cm}|}
1020 \textbf{Valore} & \textbf{Significato}\\
1023 \val{\#} & Chiede la conversione in forma alternativa. \\
1024 \val{0} & La conversione è riempita con zeri alla sinistra del valore.\\
1025 \val{-} & La conversione viene allineata a sinistra sul bordo del campo.\\
1026 \val{' '}& Mette uno spazio prima di un numero con segno di valore
1028 \val{+} & Mette sempre il segno ($+$ o $-$) prima di un numero.\\
1031 \caption{I valori dei flag per il formato di \func{printf}}
1032 \label{tab:file_format_flag}
1035 Il formato di una direttiva di conversione prevede una serie di possibili
1036 elementi opzionali oltre al \cmd{\%} e allo specificatore di conversione. In
1037 generale essa è sempre del tipo:
1040 % [n. parametro $] [flag] [[larghezza] [. precisione]] [tipo] conversione
1043 in cui tutti i valori tranne il \val{\%} e lo specificatore di conversione
1044 sono opzionali (e per questo sono indicati fra parentesi quadre); si possono
1045 usare più elementi opzionali, nel qual caso devono essere specificati in
1048 \item uno specificatore del parametro da usare (terminato da un \val{\$}),
1049 \item uno o più flag (i cui valori possibili sono riassunti in
1050 tab.~\ref{tab:file_format_flag}) che controllano il formato di stampa della
1052 \item uno specificatore di larghezza (un numero decimale), eventualmente
1053 seguito (per i numeri in virgola mobile) da un specificatore di precisione
1054 (un altro numero decimale),
1055 \item uno specificatore del tipo di dato, che ne indica la dimensione (i cui
1056 valori possibili sono riassunti in tab.~\ref{tab:file_format_type}).
1060 Dettagli ulteriori sulle varie opzioni possono essere trovati nella pagina di
1061 manuale di \func{printf} e nella documentazione delle \acr{glibc}.
1066 \begin{tabular}[c]{|l|p{10cm}|}
1068 \textbf{Valore} & \textbf{Significato} \\
1071 \cmd{hh} & Una conversione intera corrisponde a un \ctyp{char} con o senza
1072 segno, o il puntatore per il numero dei parametri \cmd{n} è di
1074 \cmd{h} & Una conversione intera corrisponde a uno \ctyp{short} con o
1075 senza segno, o il puntatore per il numero dei parametri \cmd{n}
1076 è di tipo \ctyp{short}.\\
1077 \cmd{l} & Una conversione intera corrisponde a un \ctyp{long} con o
1078 senza segno, o il puntatore per il numero dei parametri \cmd{n}
1079 è di tipo \ctyp{long}, o il carattere o la stringa seguenti
1080 sono in formato esteso.\\
1081 \cmd{ll} & Una conversione intera corrisponde a un \ctyp{long long} con o
1082 senza segno, o il puntatore per il numero dei parametri \cmd{n}
1083 è di tipo \ctyp{long long}.\\
1084 \cmd{L} & Una conversione in virgola mobile corrisponde a un
1086 \cmd{q} & Sinonimo di \cmd{ll}.\\
1087 \cmd{j} & Una conversione intera corrisponde a un \type{intmax\_t} o
1088 \type{uintmax\_t}.\\
1089 \cmd{z} & Una conversione intera corrisponde a un \type{size\_t} o
1091 \cmd{t} & Una conversione intera corrisponde a un \type{ptrdiff\_t}.\\
1094 \caption{Il modificatore di tipo di dato per il formato di \func{printf}}
1095 \label{tab:file_format_type}
1098 Una versione alternativa delle funzioni di output formattato, che permettono
1099 di usare il puntatore ad una lista variabile \index{funzioni!variadic} di
1100 argomenti (vedi sez.~\ref{sec:proc_variadic}), sono \funcd{vprintf},
1101 \funcd{vfprintf} e \funcd{vsprintf}, i cui prototipi sono:
1105 \funcdecl{int vprintf(const char *format, va\_list ap)} Stampa su
1106 \var{stdout} gli argomenti della lista \param{ap}, secondo il formato
1107 specificato da \param{format}.
1109 \funcdecl{int vfprintf(FILE *stream, const char *format, va\_list ap)}
1110 Stampa su \param{stream} gli argomenti della lista \param{ap}, secondo il
1111 formato specificato da \param{format}.
1113 \funcdecl{int vsprintf(char *str, const char *format, va\_list ap)} Stampa
1114 sulla stringa \param{str} gli argomenti della lista \param{ap}, secondo il
1115 formato specificato da \param{format}.
1117 \bodydesc{Le funzioni ritornano il numero di caratteri stampati.}
1119 \noindent con queste funzioni diventa possibile selezionare gli argomenti che
1120 si vogliono passare ad una funzione di stampa, passando direttamente la lista
1121 tramite l'argomento \param{ap}. Per poter far questo ovviamente la lista
1122 variabile\index{funzioni!variadic} degli argomenti dovrà essere opportunamente
1123 trattata (l'argomento è esaminato in sez.~\ref{sec:proc_variadic}), e dopo
1124 l'esecuzione della funzione l'argomento
1125 \param{ap} non sarà più utilizzabile (in generale dovrebbe essere eseguito un
1126 \code{va\_end(ap)} ma in Linux questo non è necessario).
1128 Come per \func{sprintf} anche per \func{vsprintf} esiste una analoga
1129 \funcd{vsnprintf} che pone un limite sul numero di caratteri che vengono
1130 scritti sulla stringa di destinazione:
1131 \begin{prototype}{stdio.h}
1132 {vsnprintf(char *str, size\_t size, const char *format, va\_list ap)}
1133 Identica a \func{vsprintf}, ma non scrive su \param{str} più di
1134 \param{size} caratteri.
1136 \noindent in modo da evitare possibili \itindex{buffer~overflow} buffer
1140 Per eliminare alla radice questi problemi, le \acr{glibc} supportano una
1141 specifica estensione GNU che alloca dinamicamente tutto lo spazio necessario;
1142 l'estensione si attiva al solito definendo \macro{\_GNU\_SOURCE}, le due
1143 funzioni sono \funcd{asprintf} e \funcd{vasprintf}, ed i rispettivi prototipi
1148 \funcdecl{int asprintf(char **strptr, const char *format, ...)} Stampa gli
1149 argomenti specificati secondo il formato specificato da \param{format} su
1150 una stringa allocata automaticamente all'indirizzo \param{*strptr}.
1152 \funcdecl{int vasprintf(char **strptr, const char *format, va\_list ap)}
1153 Stampa gli argomenti della lista \param{ap} secondo il formato specificato
1154 da \param{format} su una stringa allocata automaticamente all'indirizzo
1157 \bodydesc{Le funzioni ritornano il numero di caratteri stampati.}
1160 Entrambe le funzioni prendono come argomento \param{strptr} che deve essere
1161 l'indirizzo di un puntatore ad una stringa di caratteri, in cui verrà
1162 restituito (si ricordi quanto detto in sez.~\ref{sec:proc_var_passing} a
1163 proposito dei \itindex{value~result~argument} \textit{value result argument})
1164 l'indirizzo della stringa allocata automaticamente dalle funzioni. Occorre
1165 inoltre ricordarsi di invocare \func{free} per liberare detto puntatore quando
1166 la stringa non serve più, onde evitare \itindex{memory~leak} \textit{memory
1169 % TODO verificare se mettere prototipi di \func{dprintf} e \func{vdprintf}
1171 Infine una ulteriore estensione GNU definisce le due funzioni \funcm{dprintf} e
1172 \funcm{vdprintf}, che prendono un file descriptor al posto dello
1173 \textit{stream}. Altre estensioni permettono di scrivere con caratteri
1174 estesi. Anche queste funzioni, il cui nome è generato dalle precedenti
1175 funzioni aggiungendo una \texttt{w} davanti a \texttt{print}, sono trattate in
1176 dettaglio nella documentazione delle \acr{glibc}.
1178 In corrispondenza alla famiglia di funzioni \func{printf} che si usano per
1179 l'output formattato, l'input formattato viene eseguito con le funzioni della
1180 famiglia \func{scanf}; fra queste le tre più importanti sono \funcd{scanf},
1181 \funcd{fscanf} e \funcd{sscanf}, i cui prototipi sono:
1183 \headdecl{stdio.h} \funcdecl{int scanf(const char *format, ...)} Esegue una
1184 scansione di \file{stdin} cercando una corrispondenza di quanto letto con il
1185 formato dei dati specificato da \param{format}, ed effettua le relative
1186 conversione memorizzando il risultato negli argomenti seguenti.
1188 \funcdecl{int fscanf(FILE *stream, const char *format, ...)} Analoga alla
1189 precedente, ma effettua la scansione su \param{stream}.
1191 \funcdecl{int sscanf(char *str, const char *format, ...)} Analoga alle
1192 precedenti, ma effettua la scansione dalla stringa \param{str}.
1194 \bodydesc{Le funzioni ritornano il numero di elementi assegnati. Questi
1195 possono essere in numero inferiore a quelli specificati, ed anche zero.
1196 Quest'ultimo valore significa che non si è trovata corrispondenza. In caso
1197 di errore o fine del file viene invece restituito \val{EOF}.}
1199 \noindent e come per le analoghe funzioni di scrittura esistono le relative
1200 \funcm{vscanf}, \funcm{vfscanf} e \funcm{vsscanf} che usano un puntatore ad
1201 una lista di argomenti.
1203 Tutte le funzioni della famiglia delle \func{scanf} vogliono come argomenti i
1204 puntatori alle variabili che dovranno contenere le conversioni; questo è un
1205 primo elemento di disagio in quanto è molto facile dimenticarsi di questa
1208 Le funzioni leggono i caratteri dallo \textit{stream} (o dalla stringa) di
1209 input ed eseguono un confronto con quanto indicato in \param{format}, la
1210 sintassi di questo argomento è simile a quella usata per l'analogo di
1211 \func{printf}, ma ci sono varie differenze. Le funzioni di input infatti sono
1212 più orientate verso la lettura di testo libero che verso un input formattato
1213 in campi fissi. Uno spazio in \param{format} corrisponde con un numero
1214 qualunque di caratteri di separazione (che possono essere spazi, tabulatori,
1215 virgole ecc.), mentre caratteri diversi richiedono una corrispondenza
1216 esatta. Le direttive di conversione sono analoghe a quelle di \func{printf} e
1217 si trovano descritte in dettaglio nelle pagine di manuale e nel manuale delle
1220 Le funzioni eseguono la lettura dall'input, scartano i separatori (e gli
1221 eventuali caratteri diversi indicati dalla stringa di formato) effettuando le
1222 conversioni richieste; in caso la corrispondenza fallisca (o la funzione non
1223 sia in grado di effettuare una delle conversioni richieste) la scansione viene
1224 interrotta immediatamente e la funzione ritorna lasciando posizionato lo
1225 \textit{stream} al primo carattere che non corrisponde.
1227 Data la notevole complessità di uso di queste funzioni, che richiedono molta
1228 cura nella definizione delle corrette stringhe di formato e sono facilmente
1229 soggette ad errori, e considerato anche il fatto che è estremamente macchinoso
1230 recuperare in caso di fallimento nelle corrispondenze, l'input formattato non
1231 è molto usato. In genere infatti quando si ha a che fare con un input
1232 relativamente semplice si preferisce usare l'input di linea ed effettuare
1233 scansione e conversione di quanto serve direttamente con una delle funzioni di
1234 conversione delle stringhe; se invece il formato è più complesso diventa più
1235 facile utilizzare uno strumento come \cmd{flex}\footnote{il programma
1236 \cmd{flex}, è una implementazione libera di \cmd{lex} un generatore di
1237 analizzatori lessicali. Per i dettagli si può fare riferimento al manuale
1238 \cite{flex}.} per generare un analizzatore lessicale o il
1239 \cmd{bison}\footnote{il programma \cmd{bison} è un clone del generatore di
1240 parser \cmd{yacc}, maggiori dettagli possono essere trovati nel relativo
1241 manuale \cite{bison}.} per generare un parser.
1244 \subsection{Posizionamento su uno \textit{stream}}
1245 \label{sec:file_fseek}
1247 Come per i file descriptor anche per gli \textit{stream} è possibile spostarsi
1248 all'interno di un file per effettuare operazioni di lettura o scrittura in un
1249 punto prestabilito; sempre che l'operazione di riposizionamento sia supportata
1250 dal file sottostante lo \textit{stream}, quando cioè si ha a che fare con
1251 quello che viene detto un file ad \textsl{accesso casuale}.\footnote{dato che
1252 in un sistema Unix esistono vari tipi di file, come le fifo ed i
1253 \index{file!di~dispositivo} file di dispositivo, non è scontato che questo
1256 In GNU/Linux ed in generale in ogni sistema unix-like la posizione nel file è
1257 espressa da un intero positivo, rappresentato dal tipo \type{off\_t}, il
1258 problema è che alcune delle funzioni usate per il riposizionamento sugli
1259 \textit{stream} originano dalle prime versioni di Unix, in cui questo tipo non
1260 era ancora stato definito, e che in altri sistemi non è detto che la posizione
1261 su un file venga sempre rappresentata con il numero di caratteri dall'inizio
1262 (ad esempio in VMS può essere rappresentata come numero di record, più
1263 l'offset rispetto al record corrente).
1265 Tutto questo comporta la presenza di diverse funzioni che eseguono
1266 sostanzialmente le stesse operazioni, ma usano argomenti di tipo diverso. Le
1267 funzioni tradizionali usate per il riposizionamento della posizione in uno
1268 \textit{stream} sono \funcd{fseek} e \funcd{rewind} i cui prototipi sono:
1272 \funcdecl{int fseek(FILE *stream, long offset, int whence)} Sposta la
1273 posizione nello \textit{stream} secondo quanto specificato
1274 tramite \param{offset} e \param{whence}.
1276 \funcdecl{void rewind(FILE *stream)} Riporta la posizione nello
1277 \textit{stream} all'inizio del file.
1280 L'uso di \func{fseek} è del tutto analogo a quello di \func{lseek} per i file
1281 descriptor, e gli argomenti, a parte il tipo, hanno lo stesso significato; in
1282 particolare \param{whence} assume gli stessi valori già visti in
1283 sez.~\ref{sec:file_lseek}. La funzione restituisce 0 in caso di successo e -1
1284 in caso di errore. La funzione \func{rewind} riporta semplicemente la
1285 posizione corrente all'inizio dello \textit{stream}, ma non esattamente
1286 equivalente ad una \code{fseek(stream, 0L, SEEK\_SET)} in quanto vengono
1287 cancellati anche i flag di errore e fine del file.
1289 Per ottenere la posizione corrente si usa invece la funzione \funcd{ftell}, il
1291 \begin{prototype}{stdio.h}{long ftell(FILE *stream)}
1292 Legge la posizione attuale nello \textit{stream} \param{stream}.
1294 \bodydesc{La funzione restituisce la posizione corrente, o -1 in caso
1295 di fallimento, che può esser dovuto sia al fatto che il file non
1296 supporta il riposizionamento che al fatto che la posizione non può
1297 essere espressa con un \ctyp{long int}}
1299 \noindent la funzione restituisce la posizione come numero di byte
1300 dall'inizio dello \textit{stream}.
1302 Queste funzioni esprimono tutte la posizione nel file come un \ctyp{long int}.
1303 Dato che (ad esempio quando si usa un filesystem indicizzato a 64 bit) questo
1304 può non essere possibile lo standard POSIX ha introdotto le nuove funzioni
1305 \funcd{fgetpos} e \funcd{fsetpos}, che invece usano il nuovo tipo
1306 \type{fpos\_t}, ed i cui prototipi sono:
1310 \funcdecl{int fsetpos(FILE *stream, fpos\_t *pos)} Imposta la posizione
1311 corrente nello \textit{stream} \param{stream} al valore specificato
1314 \funcdecl{int fgetpos(FILE *stream, fpos\_t *pos)} Legge la posizione
1315 corrente nello \textit{stream} \param{stream} e la scrive in \param{pos}.
1317 \bodydesc{Le funzioni ritornano 0 in caso di successo e -1 in caso di
1321 In Linux, a partire dalle glibc 2.1, sono presenti anche le due funzioni
1322 \func{fseeko} e \func{ftello}, che sono assolutamente identiche alle
1323 precedenti \func{fseek} e \func{ftell} ma hanno argomenti di tipo
1324 \type{off\_t} anziché di tipo \ctyp{long int}. Dato che \ctyp{long} è nella
1325 gran parte dei casi un intero a 32 bit, questo diventa un problema quando la
1326 posizione sul file viene espressa con un valore a 64 bit come accade nei
1327 sistemi più moderni.
1329 % TODO: mettere prototipi espliciti fseeko e ftello o menzione?
1332 \section{Funzioni avanzate}
1333 \label{sec:file_stream_adv_func}
1335 In questa sezione esamineremo alcune funzioni avanzate che permettono di
1336 eseguire operazioni particolari sugli \textit{stream}, come leggerne gli
1337 attributi, controllarne le modalità di bufferizzazione, gestire direttamente i
1338 lock impliciti per la programmazione \itindex{thread} \textit{multi-thread}.
1341 \subsection{Le funzioni di controllo}
1342 \label{sec:file_stream_cntrl}
1344 Al contrario di quanto avviene con i file descriptor, le librerie standard del
1345 C non prevedono nessuna funzione come la \func{fcntl} per il controllo degli
1346 attributi dei file. Però, dato che ogni \textit{stream} si appoggia ad un file
1347 descriptor, si può usare la funzione \funcd{fileno} per ottenere quest'ultimo,
1348 il prototipo della funzione è:
1349 \begin{prototype}{stdio.h}{int fileno(FILE *stream)}
1350 Legge il file descriptor sottostante lo \textit{stream} \param{stream}.
1352 \bodydesc{Restituisce il numero del file descriptor in caso di successo, e
1353 -1 qualora \param{stream} non sia valido, nel qual caso imposta
1354 \var{errno} a \errval{EBADF}.}
1356 \noindent ed in questo modo diventa possibile usare direttamente \func{fcntl}.
1358 Questo permette di accedere agli attributi del file descriptor sottostante lo
1359 \textit{stream}, ma non ci dà nessuna informazione riguardo alle proprietà
1360 dello \textit{stream} medesimo. Le \acr{glibc} però supportano alcune
1361 estensioni derivate da Solaris, che permettono di ottenere informazioni utili.
1363 Ad esempio in certi casi può essere necessario sapere se un certo
1364 \textit{stream} è accessibile in lettura o scrittura. In genere questa
1365 informazione non è disponibile, e si deve ricordare come il file è stato
1366 aperto. La cosa può essere complessa se le operazioni vengono effettuate in
1367 una subroutine, che a questo punto necessiterà di informazioni aggiuntive
1368 rispetto al semplice puntatore allo \textit{stream}; questo può essere evitato
1369 con le due funzioni \funcd{\_\_freadable} e \funcd{\_\_fwritable} i cui
1372 \headdecl{stdio\_ext.h}
1373 \funcdecl{int \_\_freadable(FILE *stream)}
1374 Restituisce un valore diverso da zero se \param{stream} consente la lettura.
1376 \funcdecl{int \_\_fwritable(FILE *stream)}
1377 Restituisce un valore diverso da zero se \param{stream} consente la
1380 \noindent che permettono di ottenere questa informazione.
1382 La conoscenza dell'ultima operazione effettuata su uno \textit{stream} aperto
1383 è utile in quanto permette di trarre conclusioni sullo stato del buffer e del
1384 suo contenuto. Altre due funzioni, \funcd{\_\_freading} e \funcd{\_\_fwriting}
1385 servono a tale scopo, il loro prototipo è:
1387 \headdecl{stdio\_ext.h}
1388 \funcdecl{int \_\_freading(FILE *stream)}
1389 Restituisce un valore diverso da zero se \param{stream} è aperto in sola
1390 lettura o se l'ultima operazione è stata di lettura.
1392 \funcdecl{int \_\_fwriting(FILE *stream)}
1393 Restituisce un valore diverso da zero se \param{stream} è aperto in sola
1394 scrittura o se l'ultima operazione è stata di scrittura.
1397 Le due funzioni permettono di determinare di che tipo è stata l'ultima
1398 operazione eseguita su uno \textit{stream} aperto in lettura/scrittura;
1399 ovviamente se uno \textit{stream} è aperto in sola lettura (o sola scrittura)
1400 la modalità dell'ultima operazione è sempre determinata; l'unica ambiguità è
1401 quando non sono state ancora eseguite operazioni, in questo caso le funzioni
1402 rispondono come se una operazione ci fosse comunque stata.
1405 \subsection{Il controllo della bufferizzazione}
1406 \label{sec:file_buffering_ctrl}
1408 Come accennato in sez.~\ref{sec:file_buffering} le librerie definiscono una
1409 serie di funzioni che permettono di controllare il comportamento degli
1410 \textit{stream}; se non si è specificato nulla, la modalità di buffering viene
1411 decisa autonomamente sulla base del tipo di file sottostante, ed i buffer
1412 vengono allocati automaticamente.
1414 Però una volta che si sia aperto lo \textit{stream} (ma prima di aver compiuto
1415 operazioni su di esso) è possibile intervenire sulle modalità di buffering; la
1416 funzione che permette di controllare la bufferizzazione è \funcd{setvbuf}, il
1418 \begin{prototype}{stdio.h}{int setvbuf(FILE *stream, char *buf, int mode,
1421 Imposta la bufferizzazione dello \textit{stream} \param{stream} nella
1422 modalità indicata da \param{mode}, usando \param{buf} come buffer di
1426 \bodydesc{Restituisce zero in caso di successo, ed un valore qualunque in
1427 caso di errore, nel qual caso \var{errno} viene impostata opportunamente.}
1430 La funzione permette di controllare tutti gli aspetti della bufferizzazione;
1431 l'utente può specificare un buffer da usare al posto di quello allocato dal
1432 sistema passandone alla funzione l'indirizzo in \param{buf} e la dimensione in
1435 Ovviamente se si usa un buffer specificato dall'utente questo deve essere
1436 stato allocato e rimanere disponibile per tutto il tempo in cui si opera sullo
1437 \textit{stream}. In genere conviene allocarlo con \func{malloc} e disallocarlo
1438 dopo la chiusura del file; ma fintanto che il file è usato all'interno di una
1439 funzione, può anche essere usata una \index{variabili!automatiche} variabile
1440 automatica. In \headfile{stdio.h} è definita la macro \const{BUFSIZ}, che
1441 indica le dimensioni generiche del buffer di uno \textit{stream}; queste
1442 vengono usate dalla funzione \func{setbuf}. Non è detto però che tale
1443 dimensione corrisponda sempre al valore ottimale (che può variare a seconda
1446 Dato che la procedura di allocazione manuale è macchinosa, comporta dei rischi
1447 (come delle scritture accidentali sul buffer) e non assicura la scelta delle
1448 dimensioni ottimali, è sempre meglio lasciare allocare il buffer alle funzioni
1449 di libreria, che sono in grado di farlo in maniera ottimale e trasparente
1450 all'utente (in quanto la deallocazione avviene automaticamente). Inoltre
1451 siccome alcune implementazioni usano parte del buffer per mantenere delle
1452 informazioni di controllo, non è detto che le dimensioni dello stesso
1453 coincidano con quelle su cui viene effettuato l'I/O.
1458 \begin{tabular}[c]{|l|l|}
1460 \textbf{Valore} & \textbf{Modalità} \\
1463 \const{\_IONBF} & \textit{unbuffered}\\
1464 \const{\_IOLBF} & \textit{line buffered}\\
1465 \const{\_IOFBF} & \textit{fully buffered}\\
1468 \caption{Valori dell'argomento \param{mode} di \func{setvbuf}
1469 per l'impostazione delle modalità di bufferizzazione.}
1470 \label{tab:file_stream_buf_mode}
1473 Per evitare che \func{setvbuf} imposti il buffer basta passare un valore
1474 \val{NULL} per \param{buf} e la funzione ignorerà l'argomento \param{size}
1475 usando il buffer allocato automaticamente dal sistema. Si potrà comunque
1476 modificare la modalità di bufferizzazione, passando in \param{mode} uno degli
1477 opportuni valori elencati in tab.~\ref{tab:file_stream_buf_mode}. Qualora si
1478 specifichi la modalità non bufferizzata i valori di \param{buf} e \param{size}
1479 vengono sempre ignorati.
1481 Oltre a \func{setvbuf} le \acr{glibc} definiscono altre tre funzioni per la
1482 gestione della bufferizzazione di uno \textit{stream}: \funcd{setbuf},
1483 \funcd{setbuffer} e \funcd{setlinebuf}; i loro prototipi sono:
1487 \funcdecl{void setbuf(FILE *stream, char *buf)} Disabilita la
1488 bufferizzazione se \param{buf} è \val{NULL}, altrimenti usa \param{buf}
1489 come buffer di dimensione \const{BUFSIZ} in modalità \textit{fully buffered}.
1491 \funcdecl{void setbuffer(FILE *stream, char *buf, size\_t size)} Disabilita
1492 la bufferizzazione se \param{buf} è \val{NULL}, altrimenti usa \param{buf}
1493 come buffer di dimensione \param{size} in modalità \textit{fully buffered}.
1495 \funcdecl{void setlinebuf(FILE *stream)} Pone lo \textit{stream} in modalità
1496 \textit{line buffered}.
1498 \noindent tutte queste funzioni sono realizzate con opportune chiamate a
1499 \func{setvbuf} e sono definite solo per compatibilità con le vecchie librerie
1500 BSD. Infine le \acr{glibc} provvedono le funzioni non standard\footnote{anche
1501 queste funzioni sono originarie di Solaris.} \funcd{\_\_flbf} e
1502 \funcd{\_\_fbufsize} che permettono di leggere le proprietà di bufferizzazione
1503 di uno \textit{stream}; i cui prototipi sono:
1505 \headdecl{stdio\_ext.h}
1507 \funcdecl{int \_\_flbf(FILE *stream)} Restituisce un valore diverso da zero
1508 se \param{stream} è in modalità \textit{line buffered}.
1510 \funcdecl{size\_t \_\_fbufsize(FILE *stream)} Restituisce le dimensioni del
1511 buffer di \param{stream}.
1514 Come già accennato, indipendentemente dalla modalità di bufferizzazione
1515 scelta, si può forzare lo scarico dei dati sul file con la funzione
1516 \funcd{fflush}, il suo prototipo è:
1517 \begin{prototype}{stdio.h}{int fflush(FILE *stream)}
1519 Forza la scrittura di tutti i dati bufferizzati dello
1520 \textit{stream} \param{stream}.
1522 \bodydesc{Restituisce zero in caso di successo, ed \val{EOF} in caso di
1523 errore, impostando \var{errno} a \errval{EBADF} se \param{stream} non è
1524 aperto o non è aperto in scrittura, o ad uno degli errori di
1527 \noindent anche di questa funzione esiste una analoga
1528 \func{fflush\_unlocked}\footnote{accessibile definendo \macro{\_BSD\_SOURCE} o
1529 \macro{\_SVID\_SOURCE} o \macro{\_GNU\_SOURCE}.} che non effettua il blocco
1532 % TODO aggiungere prototipo \func{fflush\_unlocked}?
1534 Se \param{stream} è \val{NULL} lo scarico dei dati è forzato per tutti gli
1535 \textit{stream} aperti. Esistono però circostanze, ad esempio quando si vuole
1536 essere sicuri che sia stato eseguito tutto l'output su terminale, in cui serve
1537 poter effettuare lo scarico dei dati solo per gli \textit{stream} in modalità
1538 line buffered; per questo motivo le \acr{glibc} supportano una estensione di
1539 Solaris, la funzione \funcd{\_flushlbf}, il cui prototipo è:
1540 \begin{prototype}{stdio-ext.h}{void \_flushlbf(void)}
1541 Forza la scrittura di tutti i dati bufferizzati degli \textit{stream} in
1542 modalità line buffered.
1545 Si ricordi comunque che lo scarico dei dati dai buffer effettuato da queste
1546 funzioni non comporta la scrittura di questi su disco; se si vuole che il
1547 kernel dia effettivamente avvio alle operazioni di scrittura su disco occorre
1548 usare \func{sync} o \func{fsync} (si veda~sez.~\ref{sec:file_sync}).
1550 Infine esistono anche circostanze in cui si vuole scartare tutto l'output
1551 pendente; per questo si può usare \funcd{fpurge}, il cui prototipo è:
1552 \begin{prototype}{stdio.h}{int fpurge(FILE *stream)}
1554 Cancella i buffer di input e di output dello \textit{stream} \param{stream}.
1556 \bodydesc{Restituisce zero in caso di successo, ed \val{EOF} in caso di
1560 La funzione scarta tutti i dati non ancora scritti (se il file è aperto in
1561 scrittura), e tutto l'input non ancora letto (se è aperto in lettura),
1562 compresi gli eventuali caratteri rimandati indietro con \func{ungetc}.
1565 \subsection{Gli \textit{stream} e i \textit{thread}}
1566 \label{sec:file_stream_thread}
1570 Gli \textit{stream} possono essere usati in applicazioni \textit{multi-thread}
1571 allo stesso modo in cui sono usati nelle applicazioni normali, ma si deve
1572 essere consapevoli delle possibili complicazioni anche quando non si usano i
1573 \textit{thread}, dato che l'implementazione delle librerie è influenzata
1574 pesantemente dalle richieste necessarie per garantirne l'uso con i
1577 Lo standard POSIX richiede che le operazioni sui file siano atomiche rispetto
1578 ai \textit{thread}, per questo le operazioni sui buffer effettuate dalle
1579 funzioni di libreria durante la lettura e la scrittura di uno \textit{stream}
1580 devono essere opportunamente protette (in quanto il sistema assicura
1581 l'atomicità solo per le system call). Questo viene fatto associando ad ogni
1582 \textit{stream} un opportuno blocco che deve essere implicitamente acquisito
1583 prima dell'esecuzione di qualunque operazione.
1585 Ci sono comunque situazioni in cui questo non basta, come quando un
1586 \textit{thread} necessita di compiere più di una operazione sullo
1587 \textit{stream} atomicamente, per questo motivo le librerie provvedono anche
1588 delle funzioni \funcd{flockfile}, \funcd{ftrylockfile} e \funcd{funlockfile},
1589 che permettono la gestione esplicita dei blocchi sugli \textit{stream}; esse
1590 sono disponibili definendo \macro{\_POSIX\_THREAD\_SAFE\_FUNCTIONS} ed i loro
1595 \funcdecl{void flockfile(FILE *stream)} Esegue l'acquisizione del lock dello
1596 \textit{stream} \param{stream}, bloccandosi se il lock non è disponibile.
1598 \funcdecl{int ftrylockfile(FILE *stream)} Tenta l'acquisizione del lock
1599 dello \textit{stream} \param{stream}, senza bloccarsi se il lock non è
1600 disponibile. Ritorna zero in caso di acquisizione del lock, diverso da zero
1603 \funcdecl{void funlockfile(FILE *stream)} Rilascia il lock dello
1604 \textit{stream} \param{stream}.
1606 \noindent con queste funzioni diventa possibile acquisire un blocco ed
1607 eseguire tutte le operazioni volute, per poi rilasciarlo.
1609 Ma, vista la complessità delle strutture di dati coinvolte, le operazioni di
1610 blocco non sono del tutto indolori, e quando il locking dello \textit{stream}
1611 non è necessario (come in tutti i programmi che non usano i \textit{thread}),
1612 tutta la procedura può comportare dei costi pesanti in termini di
1613 prestazioni. Per questo motivo abbiamo visto come alle usuali funzioni di I/O
1614 non formattato siano associate delle versioni \code{\_unlocked} (alcune
1615 previste dallo stesso standard POSIX, altre aggiunte come estensioni dalle
1616 \acr{glibc}) che possono essere usate quando il locking non serve\footnote{in
1617 certi casi dette funzioni possono essere usate, visto che sono molto più
1618 efficienti, anche in caso di necessità di locking, una volta che questo sia
1619 stato acquisito manualmente.} con prestazioni molto più elevate, dato che
1620 spesso queste versioni (come accade per \func{getc} e \func{putc}) sono
1621 realizzate come macro.
1623 La sostituzione di tutte le funzioni di I/O con le relative versioni
1624 \code{\_unlocked} in un programma che non usa i \textit{thread} è però un
1625 lavoro abbastanza noioso; per questo motivo le \acr{glibc} forniscono al
1626 programmatore pigro un'altra via\footnote{anche questa mutuata da estensioni
1627 introdotte in Solaris.} da poter utilizzare per disabilitare in blocco il
1628 locking degli \textit{stream}: l'uso della funzione \funcd{\_\_fsetlocking},
1630 \begin{prototype}{stdio\_ext.h}{int \_\_fsetlocking (FILE *stream, int type)}
1631 Specifica o richiede a seconda del valore di \param{type} la modalità in cui
1632 le operazioni di I/O su \param{stream} vengono effettuate rispetto
1633 all'acquisizione implicita del blocco sullo \textit{stream}.
1635 \bodydesc{Restituisce lo stato di locking interno dello \textit{stream} con
1636 uno dei valori \const{FSETLOCKING\_INTERNAL} o
1637 \const{FSETLOCKING\_BYCALLER}.}
1640 La funzione imposta o legge lo stato della modalità di operazione di uno
1641 \textit{stream} nei confronti del locking a seconda del valore specificato
1642 con \param{type}, che può essere uno dei seguenti:
1643 \begin{basedescript}{\desclabelwidth{4.0cm}}
1644 \item[\const{FSETLOCKING\_INTERNAL}] Lo \textit{stream} userà da ora in poi il
1645 blocco implicito predefinito.
1646 \item[\const{FSETLOCKING\_BYCALLER}] Al ritorno della funzione sarà l'utente a
1647 dover gestire da solo il locking dello \textit{stream}.
1648 \item[\const{FSETLOCKING\_QUERY}] Restituisce lo stato corrente della modalità
1649 di blocco dello \textit{stream}.
1652 % TODO trattare \func{clearerr\_unlocked}
1659 %%% Local Variables:
1661 %%% TeX-master: "gapil"
1664 % LocalWords: stream cap system call kernel Ritchie glibc descriptor Stevens
1665 % LocalWords: buf read write filesystem st blksize stat sez l'header stdio BSD
1666 % LocalWords: nell'header stdin shell stdout stderr error freopen flush line
1667 % LocalWords: unbuffered buffered newline fully SVr fopen fdopen POSIX const
1668 % LocalWords: char path int fildes NULL errno malloc fcntl fclose fflush tab
1669 % LocalWords: dup fifo socket append EXCL ccs STRING IRUSR IWUSR IRGRP IWGRP
1670 % LocalWords: IROTH IWOTH umask fseek fsetpos rewind SEEK CUR EOF EBADF close
1671 % LocalWords: sync fcloseall SOURCE void stdlib of feof ferror clearerr l'I ws
1672 % LocalWords: unlocked fread fwrite size ptr nmemb nelem gcc padding point str
1673 % LocalWords: lock thread fgetc getc getchar dell'overhead altresì unsigned ap
1674 % LocalWords: getwc fgetwc getwchar wint wchar WEOF putc fputc putchar dell'I
1675 % LocalWords: SVID getw putw parsing peeking ahead ungetc gets fgets string Di
1676 % LocalWords: overflow Aleph stack fputs puts fgetws fputws getline ssize leak
1677 % LocalWords: realloc value result argument memory getdelim delim printf short
1678 % LocalWords: fprintf sprintf format snprintf variadic long double intmax list
1679 % LocalWords: uintmax ptrdiff vprintf vfprintf vsprintf vsnprintf asprintf lex
1680 % LocalWords: vasprintf strptr dprintf vdprintf print scanf fscanf sscanf flex
1681 % LocalWords: vscanf vfscanf vsscanf bison parser yacc like off VMS whence pos
1682 % LocalWords: lseek ftell fgetpos fpos fseeko ftello fileno Solaris freadable
1683 % LocalWords: fwritable ext freading fwriting buffering setvbuf BUFSIZ setbuf
1684 % LocalWords: IONBF IOLBF IOFBF setbuffer setlinebuf flbf fbufsize flushlbf hh
1685 % LocalWords: fsync fpurge flockfile ftrylockfile funlockfile SAFE FUNCTIONS
1686 % LocalWords: locking fsetlocking type BYCALLER QUERY ll