3 %% Copyright (C) 2000-2011 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}
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 stream è che essa provvede da sola alla
58 gestione dei dettagli della bufferizzazione e all'esecuzione delle operazioni
59 di lettura e scrittura in blocchi di dimensioni appropriate all'ottenimento
60 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 file stream restano del tutto equivalenti ai file descriptor
72 (sui quali sono basati), ed in particolare continua a valere quanto visto in
73 sez.~\ref{sec:file_sharing} a proposito dell'accesso condiviso ed in
74 sez.~\ref{sec:file_access_control} per il controllo di accesso.
79 \subsection{Gli oggetti \type{FILE}}
83 Per ragioni storiche la struttura di dati che rappresenta uno stream è stata
84 chiamata \type{FILE}, questi oggetti sono creati dalle funzioni di libreria e
85 contengono tutte le informazioni necessarie a gestire le operazioni sugli
86 stream, come la posizione corrente, lo stato del buffer e degli indicatori di
87 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 stream). Tutte le funzioni della libreria che operano sui file accettano
94 come argomenti solo variabili di questo tipo, che diventa accessibile
95 includendo l'header file \file{stdio.h}.
98 \subsection{Gli stream standard}
99 \label{sec:file_std_stream}
101 Ai tre file descriptor standard (vedi sez.~\ref{sec:file_std_descr})
102 aperti per ogni processo, corrispondono altrettanti stream, che
103 rappresentano i canali standard di input/output prestabiliti; anche
104 questi tre stream sono identificabili attraverso dei nomi simbolici
105 definiti nell'header \file{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 stream; lo scopo è quello di ridurre al minimo il numero di system call
136 (\func{read} o \func{write}) eseguite nelle operazioni di input/output. Questa
137 funzionalità è assicurata automaticamente dalla libreria, ma costituisce anche
138 uno degli aspetti più comunemente fraintesi, in particolare per quello che
139 riguarda l'aspetto della scrittura dei dati sul file.
141 I caratteri che vengono scritti su di uno stream normalmente vengono
142 accumulati in un buffer e poi trasmessi in blocco\footnote{questa operazione
143 viene usualmente chiamata \textsl{scaricamento} dei dati, dal termine
144 inglese \textit{flush}.} tutte le volte che il buffer viene riempito, in
145 maniera asincrona rispetto alla scrittura. Un comportamento analogo avviene
146 anche in lettura (cioè dal file viene letto un blocco di dati, anche se ne
147 sono richiesti una quantità inferiore), ma la cosa ovviamente ha rilevanza
148 inferiore, dato che i dati letti sono sempre gli stessi. In caso di scrittura
149 invece, quando si ha un accesso contemporaneo allo stesso file (ad esempio da
150 parte di un altro processo) si potranno vedere solo le parti effettivamente
151 scritte, e non quelle ancora presenti nel buffer.
153 Per lo stesso motivo, in tutte le situazioni in cui si sta facendo
154 dell'input/output interattivo, bisognerà tenere presente le caratteristiche
155 delle operazioni di scaricamento dei dati, poiché non è detto che ad una
156 scrittura sullo stream corrisponda una immediata scrittura sul dispositivo (la
157 cosa è particolarmente evidente quando con le operazioni di input/output su
160 Per rispondere ad esigenze diverse, lo standard definisce tre distinte
161 modalità in cui può essere eseguita la bufferizzazione, delle quali
162 occorre essere ben consapevoli, specie in caso di lettura e scrittura da
163 dispositivi interattivi:
165 \item \textit{unbuffered}: in questo caso non c'è bufferizzazione ed i
166 caratteri vengono trasmessi direttamente al file non appena possibile
167 (effettuando immediatamente una \func{write}).
168 \item \textit{line buffered}: in questo caso i caratteri vengono
169 normalmente trasmessi al file in blocco ogni volta che viene
170 incontrato un carattere di \textit{newline} (il carattere ASCII
172 \item \textit{fully buffered}: in questo caso i caratteri vengono
173 trasmessi da e verso il file in blocchi di dimensione opportuna.
176 Lo standard ANSI C specifica inoltre che lo standard output e lo
177 standard input siano aperti in modalità \textit{fully buffered} quando
178 non fanno riferimento ad un dispositivo interattivo, e che lo standard
179 error non sia mai aperto in modalità \textit{fully buffered}.
181 Linux, come BSD e SVr4, specifica il comportamento predefinito in maniera
182 ancora più precisa, e cioè impone che lo standard error sia sempre
183 \textit{unbuffered} (in modo che i messaggi di errore siano mostrati il più
184 rapidamente possibile) e che standard input e standard output siano aperti in
185 modalità \textit{line buffered} quando sono associati ad un terminale (od
186 altro dispositivo interattivo) ed in modalità \textit{fully buffered}
189 Il comportamento specificato per standard input e standard output vale anche
190 per tutti i nuovi stream aperti da un processo; la selezione comunque avviene
191 automaticamente, e la libreria apre lo stream nella modalità più opportuna a
192 seconda del file o del dispositivo scelto.
194 La modalità \textit{line buffered} è quella che necessita di maggiori
195 chiarimenti e attenzioni per quel che concerne il suo funzionamento. Come già
196 accennato nella descrizione, \emph{di norma} i dati vengono inviati al kernel
197 alla ricezione di un carattere di \textsl{a capo} (\textit{newline}); questo
198 non è vero in tutti i casi, infatti, dato che le dimensioni del buffer usato
199 dalle librerie sono fisse, se le si eccedono si può avere uno scarico dei dati
200 anche prima che sia stato inviato un carattere di \textit{newline}.
202 Un secondo punto da tenere presente, particolarmente quando si ha a che fare
203 con I/O interattivo, è che quando si effettua una lettura da uno stream che
204 comporta l'accesso al kernel\footnote{questo vuol dire che lo stream da cui si
205 legge è in modalità \textit{unbuffered}.} viene anche eseguito lo scarico di
206 tutti i buffer degli stream in scrittura.
208 In sez.~\ref{sec:file_buffering_ctrl} vedremo come la libreria definisca delle
209 opportune funzioni per controllare le modalità di bufferizzazione e lo scarico
214 \section{Funzioni base}
215 \label{sec:file_ansi_base_func}
217 Esamineremo in questa sezione le funzioni base dell'interfaccia degli stream,
218 analoghe a quelle di sez.~\ref{sec:file_base_func} per i file descriptor. In
219 particolare vedremo come aprire, leggere, scrivere e cambiare la posizione
220 corrente in uno stream.
223 \subsection{Apertura e chiusura di uno stream}
224 \label{sec:file_fopen}
226 Le funzioni che si possono usare per aprire uno stream sono solo tre:
227 \funcd{fopen}, \funcd{fdopen} e \funcd{freopen},\footnote{\func{fopen} e
228 \func{freopen} fanno parte dello standard ANSI C, \func{fdopen} è parte
229 dello standard POSIX.1.} i loro prototipi sono:
232 \funcdecl{FILE *fopen(const char *path, const char *mode)}
233 Apre il file specificato da \param{path}.
234 \funcdecl{FILE *fdopen(int fildes, const char *mode)}
235 Associa uno stream al file descriptor \param{fildes}.
236 \funcdecl{FILE *freopen(const char *path, const char *mode, FILE *stream)}
237 Apre il file specificato da \param{path} associandolo allo stream
238 specificato da \param{stream}, se questo è già aperto prima lo chiude.
240 \bodydesc{Le funzioni ritornano un puntatore valido in caso di successo e
241 \val{NULL} in caso di errore, in tal caso \var{errno} assumerà il valore
242 ricevuto dalla funzione sottostante di cui è fallita l'esecuzione.
244 Gli errori pertanto possono essere quelli di \func{malloc} per tutte
245 e tre le funzioni, quelli \func{open} per \func{fopen}, quelli di
246 \func{fcntl} per \func{fdopen} e quelli di \func{fopen},
247 \func{fclose} e \func{fflush} per \func{freopen}.}
250 Normalmente la funzione che si usa per aprire uno stream è \func{fopen},
251 essa apre il file specificato nella modalità specificata da
252 \param{mode}, che è una stringa che deve iniziare con almeno uno dei
253 valori indicati in tab.~\ref{tab:file_fopen_mode} (sono possibili varie
254 estensioni che vedremo in seguito).
256 L'uso più comune di \func{freopen} è per redirigere uno dei tre file
257 standard (vedi sez.~\ref{sec:file_std_stream}): il file \param{path} viene
258 associato a \param{stream} e se questo è uno stream già aperto viene
259 preventivamente chiuso.
261 Infine \func{fdopen} viene usata per associare uno stream ad un file
262 descriptor esistente ottenuto tramite una altra funzione (ad esempio con una
263 \func{open}, una \func{dup}, o una \func{pipe}) e serve quando si vogliono
264 usare gli stream con file come le fifo o i socket, che non possono essere
265 aperti con le funzioni delle librerie standard del C.
270 \begin{tabular}[c]{|l|p{8cm}|}
272 \textbf{Valore} & \textbf{Significato}\\
275 \texttt{r} & Il file viene aperto, l'accesso viene posto in sola
276 lettura, lo stream è posizionato all'inizio del file.\\
277 \texttt{r+}& Il file viene aperto, l'accesso viene posto in lettura e
278 scrittura, lo stream è posizionato all'inizio del file.\\
280 \texttt{w} & Il file viene aperto e troncato a lunghezza nulla (o
281 creato se non esiste), l'accesso viene posto in sola
282 scrittura, lo stream è posizionato all'inizio del file.\\
283 \texttt{w+}& Il file viene aperto e troncato a lunghezza nulla (o
284 creato se non esiste), l'accesso viene posto in scrittura e
285 lettura, lo stream è posizionato all'inizio del file.\\
287 \texttt{a} & Il file viene aperto (o creato se non esiste) in
288 \itindex{append~mode} \textit{append mode}, l'accesso viene
289 posto in sola scrittura.\\
290 \texttt{a+}& Il file viene aperto (o creato se non esiste) in
291 \itindex{append~mode} \textit{append mode}, l'accesso viene
292 posto in lettura e scrittura.\\
294 \texttt{b} & Specifica che il file è binario, non ha alcun effetto. \\
295 \texttt{x} & L'apertura fallisce se il file esiste già. \\
298 \caption{Modalità di apertura di uno stream dello standard ANSI C che
299 sono sempre presenti in qualunque sistema POSIX.}
300 \label{tab:file_fopen_mode}
303 In realtà lo standard ANSI C prevede un totale di 15 possibili valori
304 diversi per \param{mode}, ma in tab.~\ref{tab:file_fopen_mode} si sono
305 riportati solo i sei valori effettivi, ad essi può essere aggiunto pure
306 il carattere \texttt{b} (come ultimo carattere o nel mezzo agli altri per
307 le stringhe di due caratteri) che in altri sistemi operativi serve a
308 distinguere i file binari dai file di testo; in un sistema POSIX questa
309 distinzione non esiste e il valore viene accettato solo per
310 compatibilità, ma non ha alcun effetto.
312 Le \acr{glibc} supportano alcune estensioni, queste devono essere sempre
313 indicate dopo aver specificato il \param{mode} con uno dei valori di
314 tab.~\ref{tab:file_fopen_mode}. L'uso del carattere \texttt{x} serve per
315 evitare di sovrascrivere un file già esistente (è analoga all'uso
316 dell'opzione \const{O\_EXCL} in \func{open}), se il file specificato già
317 esiste e si aggiunge questo carattere a \param{mode} la \func{fopen}
320 Un'altra estensione serve a supportare la localizzazione, quando si
321 aggiunge a \param{mode} una stringa della forma \verb|",ccs=STRING"| il
322 valore \verb|STRING| è considerato il nome di una codifica dei caratteri
323 e \func{fopen} marca il file per l'uso dei caratteri estesi e abilita le
324 opportune funzioni di conversione in lettura e scrittura.
326 Nel caso si usi \func{fdopen} i valori specificati da \param{mode} devono
327 essere compatibili con quelli con cui il file descriptor è stato aperto.
328 Inoltre i modi \cmd{w} e \cmd{w+} non troncano il file. La posizione nello
329 stream viene impostata a quella corrente nel file descriptor, e le variabili
330 di errore e di fine del file (vedi sez.~\ref{sec:file_io}) sono cancellate. Il
331 file non viene duplicato e verrà chiuso alla chiusura dello stream.
333 I nuovi file saranno creati secondo quanto visto in
334 sez.~\ref{sec:file_ownership_management} ed avranno i permessi di accesso
336 \code{S\_IRUSR|S\_IWUSR|S\_IRGRP|S\_IWGRP|S\_IROTH|S\_IWOTH} (pari a
337 \val{0666}) modificato secondo il valore di \itindex{umask} \textit{umask} per
338 il processo (si veda sez.~\ref{sec:file_perm_management}).
340 In caso di file aperti in lettura e scrittura occorre ricordarsi che c'è
341 di mezzo una bufferizzazione; per questo motivo lo standard ANSI C
342 richiede che ci sia un'operazione di posizionamento fra un'operazione
343 di output ed una di input o viceversa (eccetto il caso in cui l'input ha
344 incontrato la fine del file), altrimenti una lettura può ritornare anche
345 il risultato di scritture precedenti l'ultima effettuata.
347 Per questo motivo è una buona pratica (e talvolta necessario) far seguire ad
348 una scrittura una delle funzioni \func{fflush}, \func{fseek}, \func{fsetpos} o
349 \func{rewind} prima di eseguire una rilettura; viceversa nel caso in cui si
350 voglia fare una scrittura subito dopo aver eseguito una lettura occorre prima
351 usare una delle funzioni \func{fseek}, \func{fsetpos} o \func{rewind}. Anche
352 un'operazione nominalmente nulla come \code{fseek(file, 0, SEEK\_CUR)} è
353 sufficiente a garantire la sincronizzazione.
355 Una volta aperto lo stream, si può cambiare la modalità di bufferizzazione
356 (si veda sez.~\ref{sec:file_buffering_ctrl}) fintanto che non si è effettuato
357 alcuna operazione di I/O sul file.
359 Uno stream viene chiuso con la funzione \funcd{fclose} il cui prototipo è:
360 \begin{prototype}{stdio.h}{int fclose(FILE *stream)}
361 Chiude lo stream \param{stream}.
363 \bodydesc{Restituisce 0 in caso di successo e \val{EOF} in caso di errore,
364 nel qual caso imposta \var{errno} a \errval{EBADF} se il file descriptor
365 indicato da \param{stream} non è valido, o uno dei valori specificati
366 dalla sottostante funzione che è fallita (\func{close}, \func{write} o
370 La funzione effettua lo scarico di tutti i dati presenti nei buffer di uscita
371 e scarta tutti i dati in ingresso; se era stato allocato un buffer per lo
372 stream questo verrà rilasciato. La funzione effettua lo scarico solo per i
373 dati presenti nei buffer in user space usati dalle \acr{glibc}; se si vuole
374 essere sicuri che il kernel forzi la scrittura su disco occorrerà effettuare
375 una \func{sync} (vedi sez.~\ref{sec:file_sync}).
377 Linux supporta anche una altra funzione, \funcd{fcloseall}, come estensione
378 GNU implementata dalle \acr{glibc}, accessibile avendo definito
379 \macro{\_GNU\_SOURCE}, il suo prototipo è:
380 \begin{prototype}{stdio.h}{int fcloseall(void)}
381 Chiude tutti gli stream.
383 \bodydesc{Restituisce 0 se non ci sono errori ed \val{EOF} altrimenti.}
385 \noindent la funzione esegue lo scarico dei dati bufferizzati in uscita
386 e scarta quelli in ingresso, chiudendo tutti i file. Questa funzione è
387 provvista solo per i casi di emergenza, quando si è verificato un errore
388 ed il programma deve essere abortito, ma si vuole compiere qualche altra
389 operazione dopo aver chiuso i file e prima di uscire (si ricordi quanto
390 visto in sez.~\ref{sec:proc_conclusion}).
393 \subsection{Lettura e scrittura su uno stream}
396 Una delle caratteristiche più utili dell'interfaccia degli stream è la
397 ricchezza delle funzioni disponibili per le operazioni di lettura e
398 scrittura sui file. Sono infatti previste ben tre diverse modalità
399 modalità di input/output non formattato:
401 \item\textsl{binario} in cui legge/scrive un blocco di dati alla
402 volta, vedi sez.~\ref{sec:file_binary_io}.
403 \item\textsl{a caratteri} in cui si legge/scrive un carattere alla
404 volta (con la bufferizzazione gestita automaticamente dalla libreria),
405 vedi sez.~\ref{sec:file_char_io}.
406 \item\textsl{di linea} in cui si legge/scrive una linea alla volta (terminata
407 dal carattere di newline \verb|'\n'|), vedi sez.~\ref{sec:file_line_io}.
409 ed inoltre la modalità di input/output formattato.
411 A differenza dell'interfaccia dei file descriptor, con gli stream il
412 raggiungimento della fine del file è considerato un errore, e viene
413 notificato come tale dai valori di uscita delle varie funzioni. Nella
414 maggior parte dei casi questo avviene con la restituzione del valore
415 intero (di tipo \ctyp{int}) \val{EOF}\footnote{la costante deve essere
416 negativa, le \acr{glibc} usano -1, altre implementazioni possono avere
417 valori diversi.} definito anch'esso nell'header \file{stdlib.h}.
419 Dato che le funzioni dell'interfaccia degli stream sono funzioni di libreria
420 che si appoggiano a delle system call, esse non impostano direttamente la
421 variabile \var{errno}, che mantiene il valore impostato dalla system call che
422 ha riportato l'errore.
424 Siccome la condizione di end-of-file è anch'essa segnalata come errore, nasce
425 il problema di come distinguerla da un errore effettivo; basarsi solo sul
426 valore di ritorno della funzione e controllare il valore di \var{errno}
427 infatti non basta, dato che quest'ultimo potrebbe essere stato impostato in
428 una altra occasione, (si veda sez.~\ref{sec:sys_errno} per i dettagli del
429 funzionamento di \var{errno}).
431 Per questo motivo tutte le implementazioni delle librerie standard
432 mantengono per ogni stream almeno due flag all'interno dell'oggetto
433 \type{FILE}, il flag di \textit{end-of-file}, che segnala che si è
434 raggiunta la fine del file in lettura, e quello di errore, che segnala
435 la presenza di un qualche errore nelle operazioni di input/output;
436 questi due flag possono essere riletti dalle funzioni \funcd{feof} e
437 \funcd{ferror}, i cui prototipi sono:
440 \funcdecl{int feof(FILE *stream)}
441 Controlla il flag di end-of-file di \param{stream}.
442 \funcdecl{int ferror(FILE *stream)}
443 Controlla il flag di errore di \param{stream}.
445 \bodydesc{Entrambe le funzioni ritornano un valore diverso da zero se
446 i relativi flag sono impostati.}
448 \noindent si tenga presente comunque che la lettura di questi flag segnala
449 soltanto che c'è stato un errore, o che si è raggiunta la fine del file in una
450 qualunque operazione sullo stream, il controllo quindi deve essere effettuato
451 ogni volta che si chiama una funzione di libreria.
453 Entrambi i flag (di errore e di end-of-file) possono essere cancellati usando
454 la funzione \funcd{clearerr}, il cui prototipo è:
455 \begin{prototype}{stdio.h}{void clearerr(FILE *stream)}
456 Cancella i flag di errore ed end-of-file di \param{stream}.
458 \noindent in genere si usa questa funzione una volta che si sia identificata e
459 corretta la causa di un errore per evitare di mantenere i flag attivi, così da
460 poter rilevare una successiva ulteriore condizione di errore. Di questa
461 funzione esiste una analoga \func{clearerr\_unlocked} che non esegue il blocco
462 dello stream (vedi sez.~\ref{sec:file_stream_thread}).
465 \subsection{Input/output binario}
466 \label{sec:file_binary_io}
468 La prima modalità di input/output non formattato ricalca quella della
469 interfaccia dei file descriptor, e provvede semplicemente la scrittura e la
470 lettura dei dati da un buffer verso un file e viceversa. In generale questa è
471 la modalità che si usa quando si ha a che fare con dati non formattati. Le due
472 funzioni che si usano per l'I/O binario sono \funcd{fread} ed \funcd{fwrite};
473 i loro prototipi sono:
477 \funcdecl{size\_t fread(void *ptr, size\_t size, size\_t nmemb, FILE
480 \funcdecl{size\_t fwrite(const void *ptr, size\_t size, size\_t
481 nmemb, FILE *stream)}
483 Rispettivamente leggono e scrivono \param{nmemb} elementi di dimensione
484 \param{size} dal buffer \param{ptr} al file \param{stream}.
486 \bodydesc{Entrambe le funzioni ritornano il numero di elementi letti o
487 scritti, in caso di errore o fine del file viene restituito un numero di
488 elementi inferiore al richiesto.}
491 In genere si usano queste funzioni quando si devono trasferire su file
492 blocchi di dati binari in maniera compatta e veloce; un primo caso di uso
493 tipico è quello in cui si salva un vettore (o un certo numero dei suoi
494 elementi) con una chiamata del tipo:
495 \includecodesnip{listati/WriteVect.c}
496 in questo caso devono essere specificate le dimensioni di ciascun
497 elemento ed il numero di quelli che si vogliono scrivere. Un secondo
498 caso è invece quello in cui si vuole trasferire su file una struttura;
499 si avrà allora una chiamata tipo:
500 \includecodesnip{listati/WriteStruct.c}
501 in cui si specifica la dimensione dell'intera struttura ed un solo
504 In realtà quello che conta nel trasferimento dei dati sono le dimensioni
505 totali, che sono sempre pari al prodotto \code{size * nelem}; la sola
506 differenza è che le funzioni non ritornano il numero di byte scritti,
507 ma il numero di elementi.
509 La funzione \func{fread} legge sempre un numero intero di elementi, se
510 incontra la fine del file l'oggetto letto parzialmente viene scartato
511 (lo stesso avviene in caso di errore). In questo caso la posizione dello
512 stream viene impostata alla fine del file (e non a quella corrispondente
513 alla quantità di dati letti).
515 In caso di errore (o fine del file per \func{fread}) entrambe le
516 funzioni restituiscono il numero di oggetti effettivamente letti o
517 scritti, che sarà inferiore a quello richiesto. Contrariamente a quanto
518 avviene per i file descriptor, questo segnala una condizione di errore e
519 occorrerà usare \func{feof} e \func{ferror} per stabilire la natura del
522 Benché queste funzioni assicurino la massima efficienza per il
523 salvataggio dei dati, i dati memorizzati attraverso di esse presentano
524 lo svantaggio di dipendere strettamente dalla piattaforma di sviluppo
525 usata ed in genere possono essere riletti senza problemi solo dallo
526 stesso programma che li ha prodotti.
528 Infatti diversi compilatori possono eseguire ottimizzazioni diverse delle
529 strutture dati e alcuni compilatori (come il \cmd{gcc}) possono anche
530 scegliere se ottimizzare l'occupazione di spazio, impacchettando più
531 strettamente i dati, o la velocità inserendo opportuni \textit{padding} per
532 l'allineamento dei medesimi generando quindi output binari diversi. Inoltre
533 altre incompatibilità si possono presentare quando entrano in gioco differenze
534 di architettura hardware, come la dimensione del bus o la modalità di
535 ordinamento dei bit o il formato delle variabili in floating point.
537 Per questo motivo quando si usa l'input/output binario occorre sempre prendere
538 le opportune precauzioni (in genere usare un formato di più alto livello che
539 permetta di recuperare l'informazione completa), per assicurarsi che versioni
540 diverse del programma siano in grado di rileggere i dati tenendo conto delle
541 eventuali differenze.
543 Le \acr{glibc} definiscono altre due funzioni per l'I/O binario,
544 \funcd{fread\_unlocked} e \funcd{fwrite\_unlocked} che evitano il lock
545 implicito dello stream, usato per dalla librerie per la gestione delle
546 applicazioni \itindex{thread} \textit{multi-thread} (si veda
547 sez.~\ref{sec:file_stream_thread} per i dettagli), i loro prototipi sono:
551 \funcdecl{size\_t fread\_unlocked(void *ptr, size\_t size, size\_t
552 nmemb, FILE *stream)}
554 \funcdecl{size\_t fwrite\_unlocked(const void *ptr, size\_t size,
555 size\_t nmemb, FILE *stream)}
557 \bodydesc{Le funzioni sono identiche alle analoghe \func{fread} e
558 \func{fwrite} ma non acquisiscono il lock implicito sullo stream.}
560 \noindent entrambe le funzioni sono estensioni GNU previste solo dalle
564 \subsection{Input/output a caratteri}
565 \label{sec:file_char_io}
567 La seconda modalità di input/output è quella a caratteri, in cui si
568 trasferisce un carattere alla volta. Le funzioni per la lettura a
569 caratteri sono tre, \funcd{fgetc}, \funcd{getc} e \funcd{getchar}, i
570 rispettivi prototipi sono:
574 \funcdecl{int getc(FILE *stream)} Legge un byte da \param{stream} e lo
575 restituisce come intero. In genere è implementata come una macro.
577 \funcdecl{int fgetc(FILE *stream)} Legge un byte da \param{stream} e lo
578 restituisce come intero. È sempre una funzione.
580 \funcdecl{int getchar(void)} Equivalente a \code{getc(stdin)}.
582 \bodydesc{Tutte queste funzioni leggono un byte alla volta, che viene
583 restituito come intero; in caso di errore o fine del file il valore
584 di ritorno è \val{EOF}.}
587 A parte \func{getchar}, che si usa in genere per leggere un carattere da
588 tastiera, le altre due funzioni sono sostanzialmente equivalenti. La
589 differenza è che \func{getc} è ottimizzata al massimo e normalmente
590 viene implementata con una macro, per cui occorre stare attenti a cosa
591 le si passa come argomento, infatti \param{stream} può essere valutato
592 più volte nell'esecuzione, e non viene passato in copia con il
593 meccanismo visto in sez.~\ref{sec:proc_var_passing}; per questo motivo se
594 si passa un'espressione si possono avere effetti indesiderati.
596 Invece \func{fgetc} è assicurata essere sempre una funzione, per questo motivo
597 la sua esecuzione normalmente è più lenta per via dell'overhead della
598 chiamata, ma è altresì possibile ricavarne l'indirizzo, che può essere passato
599 come argomento ad un altra funzione (e non si hanno i problemi accennati in
600 precedenza nel tipo di argomento).
602 Le tre funzioni restituiscono tutte un \ctyp{unsigned char} convertito
603 ad \ctyp{int} (si usa \ctyp{unsigned char} in modo da evitare
604 l'espansione del segno). In questo modo il valore di ritorno è sempre
605 positivo, tranne in caso di errore o fine del file.
607 Nelle estensioni GNU che provvedono la localizzazione sono definite tre
608 funzioni equivalenti alle precedenti, \funcd{getwc}, \funcd{fgetwc} e
609 \funcd{getwchar}, che invece di un carattere di un byte restituiscono un
610 carattere in formato esteso (cioè di tipo \ctyp{wint\_t}), il loro prototipo
616 \funcdecl{wint\_t getwc(FILE *stream)} Legge un carattere esteso da
617 \param{stream}. In genere è implementata come una macro.
619 \funcdecl{wint\_t fgetwc(FILE *stream)} Legge un carattere esteso da
620 \param{stream}. È una sempre una funzione.
622 \funcdecl{wint\_t getwchar(void)} Equivalente a \code{getwc(stdin)}.
624 \bodydesc{Tutte queste funzioni leggono un carattere alla volta, in
625 caso di errore o fine del file il valore di ritorno è \const{WEOF}.}
628 Per scrivere un carattere si possono usare tre funzioni, analoghe alle
629 precedenti usate per leggere: \funcd{putc}, \funcd{fputc} e \funcd{putchar}; i
634 \funcdecl{int putc(int c, FILE *stream)} Scrive il carattere \param{c}
635 su \param{stream}. In genere è implementata come una macro.
637 \funcdecl{int fputc(int c, FILE *stream)} Scrive il carattere \param{c} su
638 \param{stream}. È una sempre una funzione.
640 \funcdecl{int putchar(int c)} Equivalente a \code{putc(stdout)}.
642 \bodydesc{Le funzioni scrivono sempre un carattere alla volta, il cui
643 valore viene restituito in caso di successo; in caso di errore o
644 fine del file il valore di ritorno è \val{EOF}.}
647 Tutte queste funzioni scrivono sempre un byte alla volta, anche se prendono
648 come argomento un \ctyp{int} (che pertanto deve essere ottenuto con un cast da
649 un \ctyp{unsigned char}). Anche il valore di ritorno è sempre un intero; in
650 caso di errore o fine del file il valore di ritorno è \val{EOF}.
652 Come nel caso dell'I/O binario con \func{fread} e \func{fwrite} le \acr{glibc}
653 provvedono come estensione, per ciascuna delle funzioni precedenti,
654 un'ulteriore funzione, il cui nome è ottenuto aggiungendo un
655 \code{\_unlocked}, che esegue esattamente le stesse operazioni, evitando però
656 il lock implicito dello stream.
658 Per compatibilità con SVID sono inoltre provviste anche due funzioni,
659 \funcd{getw} e \funcd{putw}, da usare per leggere e scrivere una \textit{word}
660 (cioè due byte in una volta); i loro prototipi sono:
664 \funcdecl{int getw(FILE *stream)} Legge una parola da \param{stream}.
665 \funcdecl{int putw(int w, FILE *stream)} Scrive la parola \param{w} su
668 \bodydesc{Le funzioni restituiscono la parola \param{w}, o \val{EOF}
669 in caso di errore o di fine del file.}
672 Le funzioni leggono e scrivono una \textit{word} di due byte, usando comunque
673 una variabile di tipo \ctyp{int}; il loro uso è deprecato in favore dell'uso
674 di \func{fread} e \func{fwrite}, in quanto non è possibile distinguere il
675 valore -1 da una condizione di errore che restituisce \val{EOF}.
677 Uno degli usi più frequenti dell'input/output a caratteri è nei programmi di
678 \textit{parsing} in cui si analizza il testo; in questo contesto diventa utile
679 poter analizzare il carattere successivo da uno stream senza estrarlo
680 effettivamente (la tecnica è detta \textit{peeking ahead}) in modo che il
681 programma possa regolarsi avendo dato una \textsl{sbirciatina} a quello che
684 Nel nostro caso questo tipo di comportamento può essere realizzato prima
685 leggendo il carattere, e poi rimandandolo indietro, cosicché ridiventi
686 disponibile per una lettura successiva; la funzione che inverte la
687 lettura si chiama \funcd{ungetc} ed il suo prototipo è:
688 \begin{prototype}{stdio.h}{int ungetc(int c, FILE *stream)}
689 Rimanda indietro il carattere \param{c}, con un cast a \ctyp{unsigned
690 char}, sullo stream \param{stream}.
692 \bodydesc{La funzione ritorna \param{c} in caso di successo e
693 \val{EOF} in caso di errore.}
695 \noindent benché lo standard ANSI C preveda che l'operazione possa
696 essere ripetuta per un numero arbitrario di caratteri, alle
697 implementazioni è richiesto di garantire solo un livello; questo è
698 quello che fa la \acr{glibc}, che richiede che avvenga un'altra
699 operazione fra due \func{ungetc} successive.
701 Non è necessario che il carattere che si manda indietro sia l'ultimo che
702 si è letto, e non è necessario neanche avere letto nessun carattere
703 prima di usare \func{ungetc}, ma di norma la funzione è intesa per
704 essere usata per rimandare indietro l'ultimo carattere letto.
706 Nel caso \param{c} sia un \val{EOF} la funzione non fa nulla, e
707 restituisce sempre \val{EOF}; così si può usare \func{ungetc} anche
708 con il risultato di una lettura alla fine del file.
710 Se si è alla fine del file si può comunque rimandare indietro un
711 carattere, il flag di end-of-file verrà automaticamente cancellato
712 perché c'è un nuovo carattere disponibile che potrà essere riletto
715 Infine si tenga presente che \func{ungetc} non altera il contenuto del
716 file, ma opera esclusivamente sul buffer interno. Se si esegue una
717 qualunque delle operazioni di riposizionamento (vedi
718 sez.~\ref{sec:file_fseek}) i caratteri rimandati indietro vengono
722 \subsection{Input/output di linea}
723 \label{sec:file_line_io}
725 La terza ed ultima modalità di input/output non formattato è quella di linea,
726 in cui si legge o si scrive una riga alla volta; questa è una modalità molto
727 usata per l'I/O da terminale, ma è anche quella che presenta le
728 caratteristiche più controverse.
730 Le funzioni previste dallo standard ANSI C per leggere una linea sono
731 sostanzialmente due, \funcd{gets} e \funcd{fgets}, i cui rispettivi
736 \funcdecl{char *gets(char *string)} Scrive su \param{string} una
737 linea letta da \var{stdin}.
739 \funcdecl{char *fgets(char *string, int size, FILE *stream)}
740 Scrive su \param{string} la linea letta da \param{stream} per un
741 massimo di \param{size} byte.
743 \bodydesc{Le funzioni restituiscono l'indirizzo \param{string} in caso
744 di successo o \val{NULL} in caso di errore.}
747 Entrambe le funzioni effettuano la lettura (dal file specificato \func{fgets},
748 dallo standard input \func{gets}) di una linea di caratteri (terminata dal
749 carattere \textit{newline}, \verb|'\n'|, quello mappato sul tasto di ritorno a
750 capo della tastiera), ma \func{gets} sostituisce \verb|'\n'| con uno zero,
751 mentre \func{fgets} aggiunge uno zero dopo il \textit{newline}, che resta
752 dentro la stringa. Se la lettura incontra la fine del file (o c'è un errore)
753 viene restituito un \val{NULL}, ed il buffer \param{buf} non viene toccato.
754 L'uso di \func{gets} è deprecato e deve essere assolutamente evitato; la
755 funzione infatti non controlla il numero di byte letti, per cui nel caso la
756 stringa letta superi le dimensioni del buffer, si avrà un
757 \itindex{buffer~overflow} \textit{buffer overflow}, con sovrascrittura della
758 memoria del processo adiacente al buffer.\footnote{questa tecnica è spiegata
759 in dettaglio e con molta efficacia nell'ormai famoso articolo di Aleph1
762 Questa è una delle vulnerabilità più sfruttate per guadagnare accessi non
763 autorizzati al sistema (i cosiddetti \textit{exploit}), basta infatti inviare
764 una stringa sufficientemente lunga ed opportunamente forgiata per
765 sovrascrivere gli indirizzi di ritorno nello \itindex{stack} \textit{stack}
766 (supposto che la \func{gets} sia stata chiamata da una subroutine), in modo da
767 far ripartire l'esecuzione nel codice inviato nella stringa stessa (in genere
768 uno \textit{shell code} cioè una sezione di programma che lancia una shell).
770 La funzione \func{fgets} non ha i precedenti problemi di \func{gets} in quanto
771 prende in input la dimensione del buffer \param{size}, che non verrà mai
772 ecceduta in lettura. La funzione legge fino ad un massimo di \param{size}
773 caratteri (newline compreso), ed aggiunge uno zero di terminazione; questo
774 comporta che la stringa possa essere al massimo di \code{size-1} caratteri. Se
775 la linea eccede la dimensione del buffer verranno letti solo \code{size-1}
776 caratteri, ma la stringa sarà sempre terminata correttamente con uno zero
777 finale; sarà possibile leggere i rimanenti caratteri in una chiamata
780 Per la scrittura di una linea lo standard ANSI C prevede altre due
781 funzioni, \funcd{fputs} e \funcd{puts}, analoghe a quelle di lettura, i
782 rispettivi prototipi sono:
786 \funcdecl{int puts(const char *string)} Scrive su \var{stdout} la
787 linea \param{string}.
789 \funcdecl{int fputs(const char *string, FILE *stream)} Scrive su
790 \param{stream} la linea \param{string}.
792 \bodydesc{Le funzioni restituiscono un valore non negativo in caso di
793 successo o \val{EOF} in caso di errore.}
796 Dato che in questo caso si scrivono i dati in uscita \func{puts} non ha i
797 problemi di \func{gets} ed è in genere la forma più immediata per scrivere
798 messaggi sullo standard output; la funzione prende una stringa terminata da
799 uno zero ed aggiunge automaticamente il ritorno a capo. La differenza con
800 \func{fputs} (a parte la possibilità di specificare un file diverso da
801 \var{stdout}) è che quest'ultima non aggiunge il newline, che deve essere
802 previsto esplicitamente.
804 Come per le analoghe funzioni di input/output a caratteri, anche per l'I/O di
805 linea esistono delle estensioni per leggere e scrivere linee di caratteri
806 estesi, le funzioni in questione sono \funcd{fgetws} e \funcd{fputws} ed i
810 \funcdecl{wchar\_t *fgetws(wchar\_t *ws, int n, FILE *stream)}
811 Legge un massimo di \param{n} caratteri estesi dal file
812 \param{stream} al buffer \param{ws}.
814 \funcdecl{int fputws(const wchar\_t *ws, FILE *stream)} Scrive la
815 linea \param{ws} di caratteri estesi sul file \param{stream}.
817 \bodydesc{Le funzioni ritornano rispettivamente \param{ws} o un numero
818 non negativo in caso di successo e \val{NULL} o \val{EOF} in
819 caso di errore o fine del file.}
822 Il comportamento di queste due funzioni è identico a quello di \func{fgets} e
823 \func{fputs}, a parte il fatto che tutto (numero di caratteri massimo,
824 terminatore della stringa, newline) è espresso in termini di caratteri estesi
825 anziché di normali caratteri ASCII.
827 Come per l'I/O binario e quello a caratteri, anche per l'I/O di linea le
828 \acr{glibc} supportano una serie di altre funzioni, estensioni di tutte quelle
829 illustrate finora (eccetto \func{gets} e \func{puts}), che eseguono
830 esattamente le stesse operazioni delle loro equivalenti, evitando però il lock
831 implicito dello stream (vedi sez.~\ref{sec:file_stream_thread}). Come per le
832 altre forma di I/O, dette funzioni hanno lo stesso nome della loro analoga
833 normale, con l'aggiunta dell'estensione \code{\_unlocked}.
835 Come abbiamo visto, le funzioni di lettura per l'input/output di linea
836 previste dallo standard ANSI C presentano svariati inconvenienti. Benché
837 \func{fgets} non abbia i gravissimi problemi di \func{gets}, può
838 comunque dare risultati ambigui se l'input contiene degli zeri; questi
839 infatti saranno scritti sul buffer di uscita e la stringa in output
840 apparirà come più corta dei byte effettivamente letti. Questa è una
841 condizione che è sempre possibile controllare (deve essere presente un
842 newline prima della effettiva conclusione della stringa presente nel
843 buffer), ma a costo di una complicazione ulteriore della logica del
844 programma. Lo stesso dicasi quando si deve gestire il caso di stringa
845 che eccede le dimensioni del buffer.
847 Per questo motivo le \acr{glibc} prevedono, come estensione GNU, due nuove
848 funzioni per la gestione dell'input/output di linea, il cui uso permette di
849 risolvere questi problemi. L'uso di queste funzioni deve essere attivato
850 definendo la macro \macro{\_GNU\_SOURCE} prima di includere \file{stdio.h}. La
851 prima delle due, \funcd{getline}, serve per leggere una linea terminata da un
852 newline, esattamente allo stesso modo di \func{fgets}, il suo prototipo è:
853 \begin{prototype}{stdio.h}
854 {ssize\_t getline(char **buffer, size\_t *n, FILE *stream)} Legge una linea
855 dal file \param{stream} copiandola sul buffer indicato da \param{buffer}
856 riallocandolo se necessario (l'indirizzo del buffer e la sua dimensione
857 vengono sempre riscritte).
859 \bodydesc{La funzione ritorna il numero di caratteri letti in caso di
860 successo e -1 in caso di errore o di raggiungimento della fine del
864 La funzione permette di eseguire una lettura senza doversi preoccupare della
865 eventuale lunghezza eccessiva della stringa da leggere. Essa prende come primo
866 argomento l'indirizzo del puntatore al buffer su cui si vuole copiare la
867 linea. Quest'ultimo \emph{deve} essere stato allocato in precedenza con una
868 \func{malloc} (non si può passare l'indirizzo di un puntatore ad una variabile
869 locale); come secondo argomento la funzione vuole l'indirizzo della variabile
870 contenente le dimensioni del buffer suddetto.
872 Se il buffer di destinazione è sufficientemente ampio la stringa viene scritta
873 subito, altrimenti il buffer viene allargato usando \func{realloc} e la nuova
874 dimensione ed il nuovo puntatore vengono restituiti indietro (si noti infatti
875 come per entrambi gli argomenti si siano usati dei
876 \itindex{value~result~argument} \textit{value result argument}, passando dei
877 puntatori anziché i valori delle variabili, secondo la tecnica spiegata in
878 sez.~\ref{sec:proc_var_passing}).
880 Se si passa alla funzione l'indirizzo di un puntatore impostato a \val{NULL} e
881 \var{*n} è zero, la funzione provvede da sola all'allocazione della memoria
882 necessaria a contenere la linea. In tutti i casi si ottiene dalla funzione un
883 puntatore all'inizio del testo della linea letta. Un esempio di codice può
885 \includecodesnip{listati/getline.c}
886 e per evitare \itindex{memory~leak} \textit{memory leak} occorre ricordarsi di
887 liberare \var{ptr} con una \func{free}.
889 Il valore di ritorno della funzione indica il numero di caratteri letti
890 dallo stream (quindi compreso il newline, ma non lo zero di
891 terminazione); questo permette anche di distinguere eventuali zeri letti
892 dallo stream da quello inserito dalla funzione per terminare la linea.
893 Se si è alla fine del file e non si è potuto leggere nulla o c'è stato
894 un errore la funzione restituisce -1.
896 La seconda estensione GNU è una generalizzazione di \func{getline} per
897 poter usare come separatore un carattere qualsiasi, la funzione si
898 chiama \funcd{getdelim} ed il suo prototipo è:
899 \begin{prototype}{stdio.h}
900 {ssize\_t getdelim(char **buffer, size\_t *n, int delim, FILE *stream)}
901 Identica a \func{getline} solo che usa \param{delim} al posto del
902 carattere di newline come separatore di linea.
905 Il comportamento di \func{getdelim} è identico a quello di \func{getline} (che
906 può essere implementata da questa passando \verb|'\n'| come valore di
910 \subsection{L'input/output formattato}
911 \label{sec:file_formatted_io}
913 L'ultima modalità di input/output è quella formattata, che è una delle
914 caratteristiche più utilizzate delle librerie standard del C; in genere questa
915 è la modalità in cui si esegue normalmente l'output su terminale poiché
916 permette di stampare in maniera facile e veloce dati, tabelle e messaggi.
918 L'output formattato viene eseguito con una delle 13 funzioni della famiglia
919 \func{printf}; le tre più usate sono \funcd{printf}, \funcd{fprintf} e
920 \funcd{sprintf}, i cui prototipi sono:
923 \funcdecl{int printf(const char *format, ...)} Stampa su \file{stdout}
924 gli argomenti, secondo il formato specificato da \param{format}.
926 \funcdecl{int fprintf(FILE *stream, const char *format, ...)} Stampa
927 su \param{stream} gli argomenti, secondo il formato specificato da
930 \funcdecl{int sprintf(char *str, const char *format, ...)} Stampa
931 sulla stringa \param{str} gli argomenti, secondo il formato
932 specificato da \param{format}.
934 \bodydesc{Le funzioni ritornano il numero di caratteri stampati.}
936 \noindent le prime due servono per stampare su file (lo standard output o
937 quello specificato) la terza permette di stampare su una stringa, in genere
938 l'uso di \func{sprintf} è sconsigliato in quanto è possibile, se non si ha la
939 sicurezza assoluta sulle dimensioni del risultato della stampa, eccedere le
940 dimensioni di \param{str}, con conseguente sovrascrittura di altre variabili e
941 possibili \itindex{buffer~overflow} \textit{buffer overflow}; per questo
942 motivo si consiglia l'uso dell'alternativa \funcd{snprintf}, il cui prototipo
944 \begin{prototype}{stdio.h}
945 {snprintf(char *str, size\_t size, const char *format, ...)}
946 Identica a \func{sprintf}, ma non scrive su \param{str} più di
947 \param{size} caratteri.
950 La parte più complessa delle funzioni di scrittura formattata è il formato
951 della stringa \param{format} che indica le conversioni da fare, e da cui
952 deriva anche il numero degli argomenti che dovranno essere passati a seguire
953 (si noti come tutte queste funzioni siano \index{variadic} \textit{variadic},
954 prendendo un numero di argomenti variabile che dipende appunto da quello che
955 si è specificato in \param{format}).
960 \begin{tabular}[c]{|l|l|p{10cm}|}
962 \textbf{Valore} & \textbf{Tipo} & \textbf{Significato} \\
965 \cmd{\%d} &\ctyp{int} & Stampa un numero intero in formato decimale
967 \cmd{\%i} &\ctyp{int} & Identico a \cmd{\%i} in output.\\
968 \cmd{\%o} &\ctyp{unsigned int}& Stampa un numero intero come ottale.\\
969 \cmd{\%u} &\ctyp{unsigned int}& Stampa un numero intero in formato
970 decimale senza segno.\\
972 \cmd{\%X} &\ctyp{unsigned int}& Stampano un intero in formato esadecimale,
973 rispettivamente con lettere minuscole e
975 \cmd{\%f} &\ctyp{double} & Stampa un numero in virgola mobile con la
976 notazione a virgola fissa.\\
978 \cmd{\%E} &\ctyp{double} & Stampano un numero in virgola mobile con la
979 notazione esponenziale, rispettivamente con
980 lettere minuscole e maiuscole.\\
982 \cmd{\%G} &\ctyp{double} & Stampano un numero in virgola mobile con la
983 notazione più appropriate delle due precedenti,
984 rispettivamente con lettere minuscole e
987 \cmd{\%A} &\ctyp{double} & Stampano un numero in virgola mobile in
988 notazione esadecimale frazionaria.\\
989 \cmd{\%c} &\ctyp{int} & Stampa un carattere singolo.\\
990 \cmd{\%s} &\ctyp{char *} & Stampa una stringa.\\
991 \cmd{\%p} &\ctyp{void *} & Stampa il valore di un puntatore.\\
992 \cmd{\%n} &\ctyp{\&int} & Prende il numero di caratteri stampati finora.\\
993 \cmd{\%\%}& & Stampa un \%.\\
996 \caption{Valori possibili per gli specificatori di conversione in una
997 stringa di formato di \func{printf}.}
998 \label{tab:file_format_spec}
1001 La stringa è costituita da caratteri normali (tutti eccetto \texttt{\%}), che
1002 vengono passati invariati all'output, e da direttive di conversione, in cui
1003 devono essere sempre presenti il carattere \texttt{\%}, che introduce la
1004 direttiva, ed uno degli specificatori di conversione (riportati in
1005 tab.~\ref{tab:file_format_spec}) che la conclude.
1010 \begin{tabular}[c]{|l|p{10cm}|}
1012 \textbf{Valore} & \textbf{Significato}\\
1015 \val{\#} & Chiede la conversione in forma alternativa. \\
1016 \val{0} & La conversione è riempita con zeri alla sinistra del valore.\\
1017 \val{-} & La conversione viene allineata a sinistra sul bordo del campo.\\
1018 \val{' '}& Mette uno spazio prima di un numero con segno di valore
1020 \val{+} & Mette sempre il segno ($+$ o $-$) prima di un numero.\\
1023 \caption{I valori dei flag per il formato di \func{printf}}
1024 \label{tab:file_format_flag}
1027 Il formato di una direttiva di conversione prevede una serie di possibili
1028 elementi opzionali oltre al \cmd{\%} e allo specificatore di conversione. In
1029 generale essa è sempre del tipo:
1032 % [n. parametro $] [flag] [[larghezza] [. precisione]] [tipo] conversione
1035 in cui tutti i valori tranne il \val{\%} e lo specificatore di conversione
1036 sono opzionali (e per questo sono indicati fra parentesi quadre); si possono
1037 usare più elementi opzionali, nel qual caso devono essere specificati in
1040 \item uno specificatore del parametro da usare (terminato da un \val{\$}),
1041 \item uno o più flag (i cui valori possibili sono riassunti in
1042 tab.~\ref{tab:file_format_flag}) che controllano il formato di stampa della
1044 \item uno specificatore di larghezza (un numero decimale), eventualmente
1045 seguito (per i numeri in virgola mobile) da un specificatore di precisione
1046 (un altro numero decimale),
1047 \item uno specificatore del tipo di dato, che ne indica la dimensione (i cui
1048 valori possibili sono riassunti in tab.~\ref{tab:file_format_type}).
1052 Dettagli ulteriori sulle varie opzioni possono essere trovati nella pagina di
1053 manuale di \func{printf} e nella documentazione delle \acr{glibc}.
1058 \begin{tabular}[c]{|l|p{10cm}|}
1060 \textbf{Valore} & \textbf{Significato} \\
1063 \cmd{hh} & Una conversione intera corrisponde a un \ctyp{char} con o senza
1064 segno, o il puntatore per il numero dei parametri \cmd{n} è di
1066 \cmd{h} & Una conversione intera corrisponde a uno \ctyp{short} con o
1067 senza segno, o il puntatore per il numero dei parametri \cmd{n}
1068 è di tipo \ctyp{short}.\\
1069 \cmd{l} & Una conversione intera corrisponde a un \ctyp{long} con o
1070 senza segno, o il puntatore per il numero dei parametri \cmd{n}
1071 è di tipo \ctyp{long}, o il carattere o la stringa seguenti
1072 sono in formato esteso.\\
1073 \cmd{ll} & Una conversione intera corrisponde a un \ctyp{long long} con o
1074 senza segno, o il puntatore per il numero dei parametri \cmd{n}
1075 è di tipo \ctyp{long long}.\\
1076 \cmd{L} & Una conversione in virgola mobile corrisponde a un
1078 \cmd{q} & Sinonimo di \cmd{ll}.\\
1079 \cmd{j} & Una conversione intera corrisponde a un \type{intmax\_t} o
1080 \type{uintmax\_t}.\\
1081 \cmd{z} & Una conversione intera corrisponde a un \type{size\_t} o
1083 \cmd{t} & Una conversione intera corrisponde a un \type{ptrdiff\_t}.\\
1086 \caption{Il modificatore di tipo di dato per il formato di \func{printf}}
1087 \label{tab:file_format_type}
1090 Una versione alternativa delle funzioni di output formattato, che permettono
1091 di usare il puntatore ad una lista di argomenti (vedi
1092 sez.~\ref{sec:proc_variadic}), sono \funcd{vprintf}, \funcd{vfprintf} e
1093 \funcd{vsprintf}, i cui prototipi sono:
1097 \funcdecl{int vprintf(const char *format, va\_list ap)} Stampa su
1098 \var{stdout} gli argomenti della lista \param{ap}, secondo il formato
1099 specificato da \param{format}.
1101 \funcdecl{int vfprintf(FILE *stream, const char *format, va\_list ap)}
1102 Stampa su \param{stream} gli argomenti della lista \param{ap}, secondo il
1103 formato specificato da \param{format}.
1105 \funcdecl{int vsprintf(char *str, const char *format, va\_list ap)} Stampa
1106 sulla stringa \param{str} gli argomenti della lista \param{ap}, secondo il
1107 formato specificato da \param{format}.
1109 \bodydesc{Le funzioni ritornano il numero di caratteri stampati.}
1111 \noindent con queste funzioni diventa possibile selezionare gli argomenti che
1112 si vogliono passare ad una funzione di stampa, passando direttamente la lista
1113 tramite l'argomento \param{ap}. Per poter far questo ovviamente la lista degli
1114 argomenti dovrà essere opportunamente trattata (l'argomento è esaminato in
1115 sez.~\ref{sec:proc_variadic}), e dopo l'esecuzione della funzione l'argomento
1116 \param{ap} non sarà più utilizzabile (in generale dovrebbe essere eseguito un
1117 \code{va\_end(ap)} ma in Linux questo non è necessario).
1119 Come per \func{sprintf} anche per \func{vsprintf} esiste una analoga
1120 \funcd{vsnprintf} che pone un limite sul numero di caratteri che vengono
1121 scritti sulla stringa di destinazione:
1122 \begin{prototype}{stdio.h}
1123 {vsnprintf(char *str, size\_t size, const char *format, va\_list ap)}
1124 Identica a \func{vsprintf}, ma non scrive su \param{str} più di
1125 \param{size} caratteri.
1127 \noindent in modo da evitare possibili \itindex{buffer~overflow} buffer
1131 Per eliminare alla radice questi problemi, le \acr{glibc} supportano una
1132 specifica estensione GNU che alloca dinamicamente tutto lo spazio necessario;
1133 l'estensione si attiva al solito definendo \macro{\_GNU\_SOURCE}, le due
1134 funzioni sono \funcd{asprintf} e \funcd{vasprintf}, ed i rispettivi prototipi
1139 \funcdecl{int asprintf(char **strptr, const char *format, ...)} Stampa gli
1140 argomenti specificati secondo il formato specificato da \param{format} su
1141 una stringa allocata automaticamente all'indirizzo \param{*strptr}.
1143 \funcdecl{int vasprintf(char **strptr, const char *format, va\_list ap)}
1144 Stampa gli argomenti della lista \param{ap} secondo il formato specificato
1145 da \param{format} su una stringa allocata automaticamente all'indirizzo
1148 \bodydesc{Le funzioni ritornano il numero di caratteri stampati.}
1151 Entrambe le funzioni prendono come argomento \param{strptr} che deve essere
1152 l'indirizzo di un puntatore ad una stringa di caratteri, in cui verrà
1153 restituito (si ricordi quanto detto in sez.~\ref{sec:proc_var_passing} a
1154 proposito dei \itindex{value~result~argument} \textit{value result argument})
1155 l'indirizzo della stringa allocata automaticamente dalle funzioni. Occorre
1156 inoltre ricordarsi di invocare \func{free} per liberare detto puntatore quando
1157 la stringa non serve più, onde evitare \itindex{memory~leak} \textit{memory
1160 Infine una ulteriore estensione GNU definisce le due funzioni \func{dprintf} e
1161 \func{vdprintf}, che prendono un file descriptor al posto dello stream. Altre
1162 estensioni permettono di scrivere con caratteri estesi. Anche queste funzioni,
1163 il cui nome è generato dalle precedenti funzioni aggiungendo una \texttt{w}
1164 davanti a \texttt{print}, sono trattate in dettaglio nella documentazione delle
1167 In corrispondenza alla famiglia di funzioni \func{printf} che si usano per
1168 l'output formattato, l'input formattato viene eseguito con le funzioni della
1169 famiglia \func{scanf}; fra queste le tre più importanti sono \funcd{scanf},
1170 \funcd{fscanf} e \funcd{sscanf}, i cui prototipi sono:
1172 \headdecl{stdio.h} \funcdecl{int scanf(const char *format, ...)} Esegue una
1173 scansione di \file{stdin} cercando una corrispondenza di quanto letto con il
1174 formato dei dati specificato da \param{format}, ed effettua le relative
1175 conversione memorizzando il risultato negli argomenti seguenti.
1177 \funcdecl{int fscanf(FILE *stream, const char *format, ...)} Analoga alla
1178 precedente, ma effettua la scansione su \param{stream}.
1180 \funcdecl{int sscanf(char *str, const char *format, ...)} Analoga alle
1181 precedenti, ma effettua la scansione dalla stringa \param{str}.
1183 \bodydesc{Le funzioni ritornano il numero di elementi assegnati. Questi
1184 possono essere in numero inferiore a quelli specificati, ed anche zero.
1185 Quest'ultimo valore significa che non si è trovata corrispondenza. In caso
1186 di errore o fine del file viene invece restituito \val{EOF}.}
1188 \noindent e come per le analoghe funzioni di scrittura esistono le relative
1189 \func{vscanf}, \func{vfscanf} \func{vsscanf} che usano un puntatore ad una
1192 Tutte le funzioni della famiglia delle \func{scanf} vogliono come argomenti i
1193 puntatori alle variabili che dovranno contenere le conversioni; questo è un
1194 primo elemento di disagio in quanto è molto facile dimenticarsi di questa
1197 Le funzioni leggono i caratteri dallo stream (o dalla stringa) di input ed
1198 eseguono un confronto con quanto indicato in \param{format}, la sintassi di
1199 questo argomento è simile a quella usata per l'analogo di \func{printf}, ma ci
1200 sono varie differenze. Le funzioni di input infatti sono più orientate verso
1201 la lettura di testo libero che verso un input formattato in campi fissi. Uno
1202 spazio in \param{format} corrisponde con un numero qualunque di caratteri di
1203 separazione (che possono essere spazi, tabulatori, virgole ecc.), mentre
1204 caratteri diversi richiedono una corrispondenza esatta. Le direttive di
1205 conversione sono analoghe a quelle di \func{printf} e si trovano descritte in
1206 dettaglio nelle pagine di manuale e nel manuale delle \acr{glibc}.
1208 Le funzioni eseguono la lettura dall'input, scartano i separatori (e gli
1209 eventuali caratteri diversi indicati dalla stringa di formato) effettuando le
1210 conversioni richieste; in caso la corrispondenza fallisca (o la funzione non
1211 sia in grado di effettuare una delle conversioni richieste) la scansione viene
1212 interrotta immediatamente e la funzione ritorna lasciando posizionato lo
1213 stream al primo carattere che non corrisponde.
1215 Data la notevole complessità di uso di queste funzioni, che richiedono molta
1216 cura nella definizione delle corrette stringhe di formato e sono facilmente
1217 soggette ad errori, e considerato anche il fatto che è estremamente macchinoso
1218 recuperare in caso di fallimento nelle corrispondenze, l'input formattato non
1219 è molto usato. In genere infatti quando si ha a che fare con un input
1220 relativamente semplice si preferisce usare l'input di linea ed effettuare
1221 scansione e conversione di quanto serve direttamente con una delle funzioni di
1222 conversione delle stringhe; se invece il formato è più complesso diventa più
1223 facile utilizzare uno strumento come \cmd{flex}\footnote{il programma
1224 \cmd{flex}, è una implementazione libera di \cmd{lex} un generatore di
1225 analizzatori lessicali. Per i dettagli si può fare riferimento al manuale
1226 \cite{flex}.} per generare un analizzatore lessicale o il
1227 \cmd{bison}\footnote{il programma \cmd{bison} è un clone del generatore di
1228 parser \cmd{yacc}, maggiori dettagli possono essere trovati nel relativo
1229 manuale \cite{bison}.} per generare un parser.
1232 \subsection{Posizionamento su uno stream}
1233 \label{sec:file_fseek}
1235 Come per i file descriptor anche per gli stream è possibile spostarsi
1236 all'interno di un file per effettuare operazioni di lettura o scrittura in un
1237 punto prestabilito; sempre che l'operazione di riposizionamento sia supportata
1238 dal file sottostante lo stream, quando cioè si ha a che fare con quello che
1239 viene detto un file ad \textsl{accesso casuale}.\footnote{dato che in un
1240 sistema Unix esistono vari tipi di file, come le fifo ed i
1241 \index{file!di~dispositivo} file di dispositivo, non è scontato che questo
1244 In GNU/Linux ed in generale in ogni sistema unix-like la posizione nel file è
1245 espressa da un intero positivo, rappresentato dal tipo \type{off\_t}, il
1246 problema è che alcune delle funzioni usate per il riposizionamento sugli
1247 stream originano dalle prime versioni di Unix, in cui questo tipo non era
1248 ancora stato definito, e che in altri sistemi non è detto che la posizione su
1249 un file venga sempre rappresentata con il numero di caratteri dall'inizio (ad
1250 esempio in VMS può essere rappresentata come numero di record, più l'offset
1251 rispetto al record corrente).
1253 Tutto questo comporta la presenza di diverse funzioni che eseguono
1254 sostanzialmente le stesse operazioni, ma usano argomenti di tipo diverso. Le
1255 funzioni tradizionali usate per il riposizionamento della posizione in uno
1256 stream sono \funcd{fseek} e \funcd{rewind} i cui prototipi sono:
1260 \funcdecl{int fseek(FILE *stream, long offset, int whence)} Sposta la
1261 posizione nello stream secondo quanto specificato tramite \param{offset}
1264 \funcdecl{void rewind(FILE *stream)} Riporta la posizione nello stream
1265 all'inizio del file.
1268 L'uso di \func{fseek} è del tutto analogo a quello di \func{lseek} per i file
1269 descriptor, e gli argomenti, a parte il tipo, hanno lo stesso significato; in
1270 particolare \param{whence} assume gli stessi valori già visti in
1271 sez.~\ref{sec:file_lseek}. La funzione restituisce 0 in caso di successo e -1
1272 in caso di errore. La funzione \func{rewind} riporta semplicemente la
1273 posizione corrente all'inizio dello stream, ma non esattamente equivalente ad
1274 una \code{fseek(stream, 0L, SEEK\_SET)} in quanto vengono cancellati anche i
1275 flag di errore e fine del file.
1277 Per ottenere la posizione corrente si usa invece la funzione \funcd{ftell}, il
1279 \begin{prototype}{stdio.h}{long ftell(FILE *stream)}
1280 Legge la posizione attuale nello stream \param{stream}.
1282 \bodydesc{La funzione restituisce la posizione corrente, o -1 in caso
1283 di fallimento, che può esser dovuto sia al fatto che il file non
1284 supporta il riposizionamento che al fatto che la posizione non può
1285 essere espressa con un \ctyp{long int}}
1287 \noindent la funzione restituisce la posizione come numero di byte
1288 dall'inizio dello stream.
1290 Queste funzioni esprimono tutte la posizione nel file come un \ctyp{long int}.
1291 Dato che (ad esempio quando si usa un filesystem indicizzato a 64 bit) questo
1292 può non essere possibile lo standard POSIX ha introdotto le nuove funzioni
1293 \funcd{fgetpos} e \funcd{fsetpos}, che invece usano il nuovo tipo
1294 \type{fpos\_t}, ed i cui prototipi sono:
1298 \funcdecl{int fsetpos(FILE *stream, fpos\_t *pos)} Imposta la posizione
1299 corrente nello stream \param{stream} al valore specificato da \param{pos}.
1301 \funcdecl{int fgetpos(FILE *stream, fpos\_t *pos)} Legge la posizione
1302 corrente nello stream \param{stream} e la scrive in \param{pos}.
1304 \bodydesc{Le funzioni ritornano 0 in caso di successo e -1 in caso di
1308 In Linux, a partire dalle glibc 2.1, sono presenti anche le due funzioni
1309 \func{fseeko} e \func{ftello}, che sono assolutamente identiche alle
1310 precedenti \func{fseek} e \func{ftell} ma hanno argomenti di tipo
1311 \type{off\_t} anziché di tipo \ctyp{long int}. Dato che \ctyp{long} è nella
1312 gran parte dei casi un intero a 32 bit, questo diventa un problema quando la
1313 posizione sul file viene espressa con un valore a 64 bit come accade nei
1314 sistemi più moderni.
1318 \section{Funzioni avanzate}
1319 \label{sec:file_stream_adv_func}
1321 In questa sezione esamineremo alcune funzioni avanzate che permettono di
1322 eseguire operazioni particolari sugli stream, come leggerne gli attributi,
1323 controllarne le modalità di bufferizzazione, gestire direttamente i lock
1324 impliciti per la programmazione \itindex{thread} \textit{multi-thread}.
1327 \subsection{Le funzioni di controllo}
1328 \label{sec:file_stream_cntrl}
1330 Al contrario di quanto avviene con i file descriptor, le librerie standard del
1331 C non prevedono nessuna funzione come la \func{fcntl} per il controllo degli
1332 attributi dei file. Però, dato che ogni stream si appoggia ad un file
1333 descriptor, si può usare la funzione \funcd{fileno} per ottenere quest'ultimo,
1334 il prototipo della funzione è:
1335 \begin{prototype}{stdio.h}{int fileno(FILE *stream)}
1336 Legge il file descriptor sottostante lo stream \param{stream}.
1338 \bodydesc{Restituisce il numero del file descriptor in caso di successo, e
1339 -1 qualora \param{stream} non sia valido, nel qual caso imposta
1340 \var{errno} a \errval{EBADF}.}
1342 \noindent ed in questo modo diventa possibile usare direttamente \func{fcntl}.
1344 Questo permette di accedere agli attributi del file descriptor sottostante lo
1345 stream, ma non ci dà nessuna informazione riguardo alle proprietà dello stream
1346 medesimo. Le \acr{glibc} però supportano alcune estensioni derivate da
1347 Solaris, che permettono di ottenere informazioni utili.
1349 Ad esempio in certi casi può essere necessario sapere se un certo stream è
1350 accessibile in lettura o scrittura. In genere questa informazione non è
1351 disponibile, e si deve ricordare come il file è stato aperto. La cosa può
1352 essere complessa se le operazioni vengono effettuate in una subroutine, che a
1353 questo punto necessiterà di informazioni aggiuntive rispetto al semplice
1354 puntatore allo stream; questo può essere evitato con le due funzioni
1355 \funcd{\_\_freadable} e \funcd{\_\_fwritable} i cui prototipi sono:
1357 \headdecl{stdio\_ext.h}
1358 \funcdecl{int \_\_freadable(FILE *stream)}
1359 Restituisce un valore diverso da zero se \param{stream} consente la lettura.
1361 \funcdecl{int \_\_fwritable(FILE *stream)}
1362 Restituisce un valore diverso da zero se \param{stream} consente la
1365 \noindent che permettono di ottenere questa informazione.
1367 La conoscenza dell'ultima operazione effettuata su uno stream aperto è utile
1368 in quanto permette di trarre conclusioni sullo stato del buffer e del suo
1369 contenuto. Altre due funzioni, \funcd{\_\_freading} e \funcd{\_\_fwriting}
1370 servono a tale scopo, il loro prototipo è:
1372 \headdecl{stdio\_ext.h}
1373 \funcdecl{int \_\_freading(FILE *stream)}
1374 Restituisce un valore diverso da zero se \param{stream} è aperto in sola
1375 lettura o se l'ultima operazione è stata di lettura.
1377 \funcdecl{int \_\_fwriting(FILE *stream)}
1378 Restituisce un valore diverso da zero se \param{stream} è aperto in sola
1379 scrittura o se l'ultima operazione è stata di scrittura.
1382 Le due funzioni permettono di determinare di che tipo è stata l'ultima
1383 operazione eseguita su uno stream aperto in lettura/scrittura; ovviamente se
1384 uno stream è aperto in sola lettura (o sola scrittura) la modalità dell'ultima
1385 operazione è sempre determinata; l'unica ambiguità è quando non sono state
1386 ancora eseguite operazioni, in questo caso le funzioni rispondono come se una
1387 operazione ci fosse comunque stata.
1390 \subsection{Il controllo della bufferizzazione}
1391 \label{sec:file_buffering_ctrl}
1393 Come accennato in sez.~\ref{sec:file_buffering} le librerie definiscono una
1394 serie di funzioni che permettono di controllare il comportamento degli stream;
1395 se non si è specificato nulla, la modalità di buffering viene decisa
1396 autonomamente sulla base del tipo di file sottostante, ed i buffer vengono
1397 allocati automaticamente.
1399 Però una volta che si sia aperto lo stream (ma prima di aver compiuto
1400 operazioni su di esso) è possibile intervenire sulle modalità di buffering; la
1401 funzione che permette di controllare la bufferizzazione è \funcd{setvbuf}, il
1403 \begin{prototype}{stdio.h}{int setvbuf(FILE *stream, char *buf, int mode,
1406 Imposta la bufferizzazione dello stream \param{stream} nella modalità
1407 indicata da \param{mode}, usando \param{buf} come buffer di lunghezza
1410 \bodydesc{Restituisce zero in caso di successo, ed un valore qualunque in
1411 caso di errore, nel qual caso \var{errno} viene impostata opportunamente.}
1414 La funzione permette di controllare tutti gli aspetti della bufferizzazione;
1415 l'utente può specificare un buffer da usare al posto di quello allocato dal
1416 sistema passandone alla funzione l'indirizzo in \param{buf} e la dimensione in
1419 Ovviamente se si usa un buffer specificato dall'utente questo deve essere
1420 stato allocato e rimanere disponibile per tutto il tempo in cui si opera sullo
1421 stream. In genere conviene allocarlo con \func{malloc} e disallocarlo dopo la
1422 chiusura del file; ma fintanto che il file è usato all'interno di una
1423 funzione, può anche essere usata una \index{variabili!automatiche} variabile
1424 automatica. In \file{stdio.h} è definita la macro \const{BUFSIZ}, che indica
1425 le dimensioni generiche del buffer di uno stream; queste vengono usate dalla
1426 funzione \func{setbuf}. Non è detto però che tale dimensione corrisponda
1427 sempre al valore ottimale (che può variare a seconda del dispositivo).
1429 Dato che la procedura di allocazione manuale è macchinosa, comporta dei rischi
1430 (come delle scritture accidentali sul buffer) e non assicura la scelta delle
1431 dimensioni ottimali, è sempre meglio lasciare allocare il buffer alle funzioni
1432 di libreria, che sono in grado di farlo in maniera ottimale e trasparente
1433 all'utente (in quanto la deallocazione avviene automaticamente). Inoltre
1434 siccome alcune implementazioni usano parte del buffer per mantenere delle
1435 informazioni di controllo, non è detto che le dimensioni dello stesso
1436 coincidano con quelle su cui viene effettuato l'I/O.
1441 \begin{tabular}[c]{|l|l|}
1443 \textbf{Valore} & \textbf{Modalità} \\
1446 \const{\_IONBF} & \textit{unbuffered}\\
1447 \const{\_IOLBF} & \textit{line buffered}\\
1448 \const{\_IOFBF} & \textit{fully buffered}\\
1451 \caption{Valori dell'argomento \param{mode} di \func{setvbuf}
1452 per l'impostazione delle modalità di bufferizzazione.}
1453 \label{tab:file_stream_buf_mode}
1456 Per evitare che \func{setvbuf} imposti il buffer basta passare un valore
1457 \val{NULL} per \param{buf} e la funzione ignorerà l'argomento \param{size}
1458 usando il buffer allocato automaticamente dal sistema. Si potrà comunque
1459 modificare la modalità di bufferizzazione, passando in \param{mode} uno degli
1460 opportuni valori elencati in tab.~\ref{tab:file_stream_buf_mode}. Qualora si
1461 specifichi la modalità non bufferizzata i valori di \param{buf} e \param{size}
1462 vengono sempre ignorati.
1464 Oltre a \func{setvbuf} le \acr{glibc} definiscono altre tre funzioni per la
1465 gestione della bufferizzazione di uno stream: \funcd{setbuf}, \funcd{setbuffer}
1466 e \funcd{setlinebuf}; i loro prototipi sono:
1470 \funcdecl{void setbuf(FILE *stream, char *buf)} Disabilita la
1471 bufferizzazione se \param{buf} è \val{NULL}, altrimenti usa \param{buf}
1472 come buffer di dimensione \const{BUFSIZ} in modalità \textit{fully buffered}.
1474 \funcdecl{void setbuffer(FILE *stream, char *buf, size\_t size)} Disabilita
1475 la bufferizzazione se \param{buf} è \val{NULL}, altrimenti usa \param{buf}
1476 come buffer di dimensione \param{size} in modalità \textit{fully buffered}.
1478 \funcdecl{void setlinebuf(FILE *stream)} Pone lo stream in modalità
1479 \textit{line buffered}.
1481 \noindent tutte queste funzioni sono realizzate con opportune chiamate a
1482 \func{setvbuf} e sono definite solo per compatibilità con le vecchie librerie
1483 BSD. Infine le \acr{glibc} provvedono le funzioni non standard\footnote{anche
1484 queste funzioni sono originarie di Solaris.} \funcd{\_\_flbf} e
1485 \funcd{\_\_fbufsize} che permettono di leggere le proprietà di bufferizzazione
1486 di uno stream; i cui prototipi sono:
1488 \headdecl{stdio\_ext.h}
1490 \funcdecl{int \_\_flbf(FILE *stream)} Restituisce un valore diverso da zero
1491 se \param{stream} è in modalità \textit{line buffered}.
1493 \funcdecl{size\_t \_\_fbufsize(FILE *stream)} Restituisce le dimensioni del
1494 buffer di \param{stream}.
1497 Come già accennato, indipendentemente dalla modalità di bufferizzazione
1498 scelta, si può forzare lo scarico dei dati sul file con la funzione
1499 \funcd{fflush}, il suo prototipo è:
1500 \begin{prototype}{stdio.h}{int fflush(FILE *stream)}
1502 Forza la scrittura di tutti i dati bufferizzati dello stream \param{stream}.
1504 \bodydesc{Restituisce zero in caso di successo, ed \val{EOF} in caso di
1505 errore, impostando \var{errno} a \errval{EBADF} se \param{stream} non è
1506 aperto o non è aperto in scrittura, o ad uno degli errori di
1509 \noindent anche di questa funzione esiste una analoga
1510 \func{fflush\_unlocked}\footnote{accessibile definendo \macro{\_BSD\_SOURCE} o
1511 \macro{\_SVID\_SOURCE} o \macro{\_GNU\_SOURCE}.} che non effettua il blocco
1514 Se \param{stream} è \val{NULL} lo scarico dei dati è forzato per tutti gli
1515 stream aperti. Esistono però circostanze, ad esempio quando si vuole essere
1516 sicuri che sia stato eseguito tutto l'output su terminale, in cui serve poter
1517 effettuare lo scarico dei dati solo per gli stream in modalità line buffered;
1518 per questo motivo le \acr{glibc} supportano una estensione di Solaris, la
1519 funzione \funcd{\_flushlbf}, il cui prototipo è:
1520 \begin{prototype}{stdio-ext.h}{void \_flushlbf(void)}
1521 Forza la scrittura di tutti i dati bufferizzati degli stream in modalità
1525 Si ricordi comunque che lo scarico dei dati dai buffer effettuato da queste
1526 funzioni non comporta la scrittura di questi su disco; se si vuole che il
1527 kernel dia effettivamente avvio alle operazioni di scrittura su disco occorre
1528 usare \func{sync} o \func{fsync} (si veda~sez.~\ref{sec:file_sync}).
1530 Infine esistono anche circostanze in cui si vuole scartare tutto l'output
1531 pendente; per questo si può usare \funcd{fpurge}, il cui prototipo è:
1532 \begin{prototype}{stdio.h}{int fpurge(FILE *stream)}
1534 Cancella i buffer di input e di output dello stream \param{stream}.
1536 \bodydesc{Restituisce zero in caso di successo, ed \val{EOF} in caso di
1540 La funzione scarta tutti i dati non ancora scritti (se il file è aperto in
1541 scrittura), e tutto l'input non ancora letto (se è aperto in lettura),
1542 compresi gli eventuali caratteri rimandati indietro con \func{ungetc}.
1545 \subsection{Gli \textit{stream} e i \textit{thread}}
1546 \label{sec:file_stream_thread}
1550 Gli stream possono essere usati in applicazioni \textit{multi-thread} allo
1551 stesso modo in cui sono usati nelle applicazioni normali, ma si deve essere
1552 consapevoli delle possibili complicazioni anche quando non si usano i
1553 \textit{thread}, dato che l'implementazione delle librerie è influenzata
1554 pesantemente dalle richieste necessarie per garantirne l'uso con i
1557 Lo standard POSIX richiede che le operazioni sui file siano atomiche rispetto
1558 ai \textit{thread}, per questo le operazioni sui buffer effettuate dalle
1559 funzioni di libreria durante la lettura e la scrittura di uno stream devono
1560 essere opportunamente protette (in quanto il sistema assicura l'atomicità solo
1561 per le system call). Questo viene fatto associando ad ogni stream un opportuno
1562 blocco che deve essere implicitamente acquisito prima dell'esecuzione di
1563 qualunque operazione.
1565 Ci sono comunque situazioni in cui questo non basta, come quando un
1566 \textit{thread} necessita di compiere più di una operazione sullo stream
1567 atomicamente, per questo motivo le librerie provvedono anche delle funzioni
1568 \funcd{flockfile}, \funcd{ftrylockfile} e \funcd{funlockfile}, che permettono
1569 la gestione esplicita dei blocchi sugli stream; esse sono disponibili
1570 definendo \macro{\_POSIX\_THREAD\_SAFE\_FUNCTIONS} ed i loro prototipi sono:
1574 \funcdecl{void flockfile(FILE *stream)} Esegue l'acquisizione del lock dello
1575 stream \param{stream}, bloccandosi se il lock non è disponibile.
1577 \funcdecl{int ftrylockfile(FILE *stream)} Tenta l'acquisizione del lock
1578 dello stream \param{stream}, senza bloccarsi se il lock non è disponibile.
1579 Ritorna zero in caso di acquisizione del lock, diverso da zero altrimenti.
1581 \funcdecl{void funlockfile(FILE *stream)} Rilascia il lock dello
1582 stream \param{stream}.
1584 \noindent con queste funzioni diventa possibile acquisire un blocco ed
1585 eseguire tutte le operazioni volute, per poi rilasciarlo.
1587 Ma, vista la complessità delle strutture di dati coinvolte, le operazioni di
1588 blocco non sono del tutto indolori, e quando il locking dello stream non è
1589 necessario (come in tutti i programmi che non usano i \textit{thread}), tutta
1590 la procedura può comportare dei costi pesanti in termini di prestazioni. Per
1591 questo motivo abbiamo visto come alle usuali funzioni di I/O non formattato
1592 siano associate delle versioni \code{\_unlocked} (alcune previste dallo stesso
1593 standard POSIX, altre aggiunte come estensioni dalle \acr{glibc}) che possono
1594 essere usate quando il locking non serve\footnote{in certi casi dette funzioni
1595 possono essere usate, visto che sono molto più efficienti, anche in caso di
1596 necessità di locking, una volta che questo sia stato acquisito manualmente.}
1597 con prestazioni molto più elevate, dato che spesso queste versioni (come
1598 accade per \func{getc} e \func{putc}) sono realizzate come macro.
1600 La sostituzione di tutte le funzioni di I/O con le relative versioni
1601 \code{\_unlocked} in un programma che non usa i \textit{thread} è però un
1602 lavoro abbastanza noioso; per questo motivo le \acr{glibc} forniscono al
1603 programmatore pigro un'altra via\footnote{anche questa mutuata da estensioni
1604 introdotte in Solaris.} da poter utilizzare per disabilitare in blocco il
1605 locking degli stream: l'uso della funzione \funcd{\_\_fsetlocking}, il cui
1607 \begin{prototype}{stdio\_ext.h}{int \_\_fsetlocking (FILE *stream, int type)}
1608 Specifica o richiede a seconda del valore di \param{type} la modalità in cui
1609 le operazioni di I/O su \param{stream} vengono effettuate rispetto
1610 all'acquisizione implicita del blocco sullo stream.
1612 \bodydesc{Restituisce lo stato di locking interno dello stream con uno dei
1613 valori \const{FSETLOCKING\_INTERNAL} o \const{FSETLOCKING\_BYCALLER}.}
1616 La funzione imposta o legge lo stato della modalità di operazione di uno stream
1617 nei confronti del locking a seconda del valore specificato con \param{type},
1618 che può essere uno dei seguenti:
1619 \begin{basedescript}{\desclabelwidth{4.0cm}}
1620 \item[\const{FSETLOCKING\_INTERNAL}] Lo stream userà da ora in poi il blocco
1621 implicito predefinito.
1622 \item[\const{FSETLOCKING\_BYCALLER}] Al ritorno della funzione sarà l'utente a
1623 dover gestire da solo il locking dello stream.
1624 \item[\const{FSETLOCKING\_QUERY}] Restituisce lo stato corrente della modalità
1625 di blocco dello stream.
1632 %%% Local Variables:
1634 %%% TeX-master: "gapil"
1637 % LocalWords: stream cap system call kernel Ritchie glibc descriptor Stevens
1638 % LocalWords: buf read write filesystem st blksize stat sez l'header stdio BSD
1639 % LocalWords: nell'header stdin shell stdout stderr error freopen flush line
1640 % LocalWords: unbuffered buffered newline fully SVr fopen fdopen POSIX const
1641 % LocalWords: char path int fildes NULL errno malloc fcntl fclose fflush tab
1642 % LocalWords: dup fifo socket append EXCL ccs STRING IRUSR IWUSR IRGRP IWGRP
1643 % LocalWords: IROTH IWOTH umask fseek fsetpos rewind SEEK CUR EOF EBADF close
1644 % LocalWords: sync fcloseall SOURCE void stdlib of feof ferror clearerr l'I ws
1645 % LocalWords: unlocked fread fwrite size ptr nmemb nelem gcc padding point str
1646 % LocalWords: lock thread fgetc getc getchar dell'overhead altresì unsigned ap
1647 % LocalWords: getwc fgetwc getwchar wint wchar WEOF putc fputc putchar dell'I
1648 % LocalWords: SVID getw putw parsing peeking ahead ungetc gets fgets string Di
1649 % LocalWords: overflow Aleph stack fputs puts fgetws fputws getline ssize leak
1650 % LocalWords: realloc value result argument memory getdelim delim printf short
1651 % LocalWords: fprintf sprintf format snprintf variadic long double intmax list
1652 % LocalWords: uintmax ptrdiff vprintf vfprintf vsprintf vsnprintf asprintf lex
1653 % LocalWords: vasprintf strptr dprintf vdprintf print scanf fscanf sscanf flex
1654 % LocalWords: vscanf vfscanf vsscanf bison parser yacc like off VMS whence pos
1655 % LocalWords: lseek ftell fgetpos fpos fseeko ftello fileno Solaris freadable
1656 % LocalWords: fwritable ext freading fwriting buffering setvbuf BUFSIZ setbuf
1657 % LocalWords: IONBF IOLBF IOFBF setbuffer setlinebuf flbf fbufsize flushlbf hh
1658 % LocalWords: fsync fpurge flockfile ftrylockfile funlockfile SAFE FUNCTIONS
1659 % LocalWords: locking fsetlocking type BYCALLER QUERY ll