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