\begin{prototype}{stdio.h}{int fclose(FILE * stream)}
Chiude lo stream \param{stream}.
- Restituisce 0 in caso di successo e \macro{EOF} in caso di errore, nel qual
- caso setta \var{errno} a \macro{EBADF} se il file descriptor indicato da
- \param{stream} non è valido, o uno dei valori specificati dalla sottostante
- funzione che è fallita (\func{close}, \func{write} o \func{fflush}).
+ \bodydesc{Restituisce 0 in caso di successo e \macro{EOF} in caso di errore,
+ nel qual caso setta \var{errno} a \macro{EBADF} se il file descriptor
+ indicato da \param{stream} non è valido, o uno dei valori specificati
+ dalla sottostante funzione che è fallita (\func{close}, \func{write} o
+ \func{fflush}).}
\end{prototype}
La funzione effettua uno scarico di tutti i dati presenti nei buffer di
\begin{prototype}{stdio.h}{int fcloseall(void)}
Chiude tutti gli stream.
- Restituisce 0 se non ci sono errori ed \macro{EOF} altrimenti.
+ \bodydesc{Restituisce 0 se non ci sono errori ed \macro{EOF} altrimenti.}
\end{prototype}
la funzione esegue lo scarico dei dati bufferizzati in uscita e scarta quelli
in ingresso, chiudendo tutti i file. Questa funzione è provvista solo per i
\funcdecl{size\_t fwrite(const void * ptr, size\_t size, size\_t
nmemb, FILE * stream)}
- Le funzioni rispettivamente leggono e scrivono \param{nmemb} elementi
- di dimensione \param{size} dal buffer \param{ptr} al file
- \param{stream}.
+ Rispettivamente leggono e scrivono \param{nmemb} elementi di dimensione
+ \param{size} dal buffer \param{ptr} al file \param{stream}.
- Entrambe le funzioni ritornano il numero di elementi letti o scritti,
- in caso di errore o fine del file viene restituito un numero di
- elementi inferiore al richiesto.
+ \bodydesc{Entrambe le funzioni ritornano il numero di elementi letti o
+ scritti, in caso di errore o fine del file viene restituito un numero di
+ elementi inferiore al richiesto.}
\end{functions}
In genere si usano queste funzioni quando si devono trasferire su file
\funcdecl{size\_t fwrite\_unlocked(const void * ptr, size\_t size,
size\_t nmemb, FILE * stream)}
- Le funzioni sono identiche alle analoghe \func{fread} e \func{fwrite}
- ma non acquisiscono il lock implicito sullo stream.
+ \bodydesc{Le funzioni sono identiche alle analoghe \func{fread} e
+ \func{fwrite} ma non acquisiscono il lock implicito sullo stream.}
\end{functions}
\noindent entrambe le funzioni sono estensioni GNU previste solo dalle
\acr{glibc}.
\funcdecl{int fgetc(FILE *stream)} Legge un byte da \param{stream} e lo
restituisce come intero. È una sempre una funzione.
- \funcdecl{int getchar(void)} è equivalente a \func{getc(stdin)}.
+ \funcdecl{int getchar(void)} Equivalente a \func{getc(stdin)}.
\bodydesc{Tutte queste funzioni leggono un byte alla volta, che viene
restituito come intero; in caso di errore o fine del file il valore
l'espansione del segno). In questo modo il valore di ritorno è sempre
positivo, tranne in caso di errore o fine del file.
-Nelle estenzioni GNU che provvedono la localizzazione sono definite tre
+Nelle estensioni GNU che provvedono la localizzazione sono definite tre
funzioni equivalenti alle precedenti che invece di un carattere di un
byte restituiscono un carattere in formato esteso (cioè di tipo
\type{wint\_t}, il loro prototipo è:
\funcdecl{wint\_t fgetwc(FILE *stream)} Legge un carattere esteso da
\param{stream} È una sempre una funzione.
- \funcdecl{wint\_t getwchar(void)} è equivalente a \func{getwc(stdin)}.
+ \funcdecl{wint\_t getwchar(void)} Equivalente a \func{getwc(stdin)}.
\bodydesc{Tutte queste funzioni leggono un carattere alla volta, in
caso di errore o fine del file il valore di ritorno è \macro{WEOF}.}
\funcdecl{int fputc(FILE *stream)} Scrive il carattere \param{c} su
\param{stream}. È una sempre una funzione.
- \funcdecl{int putchar(void)} è equivalente a \func{putc(stdin)}.
+ \funcdecl{int putchar(void)} Equivalente a \func{putc(stdin)}.
\bodydesc{Le funzioni scrivono sempre un carattere alla volta, il cui
valore viene restituito in caso di successo; in caso di errore o
dato una \textsl{sbirciatina} a quello che viene dopo.
Nel nostro caso questo tipo di comportamento può essere realizzato prima
-leggendo il carattere, e poi rimandandolo indietro, cosicchè ridiventi
+leggendo il carattere, e poi rimandandolo indietro, cosicché ridiventi
disponibile per una lettura successiva; la funzione che inverte la
lettura si chiama \func{ungetc} ed il suo prototipo è:
\begin{prototype}{stdio.h}{int ungetc(int c, FILE *stream)}
- Cancella i flag di errore ed end-of-file di \param{stream}.
+ Rimanda indietro il carattere \param{c}, con un cast a \type{unsigned
+ char}, sullo stream \param{stream}.
+
+ \bodydesc{La funzione ritorna \param{c} in caso di successo e
+ \macro{EOF} in caso di errore.}
\end{prototype}
+benché lo standard ANSI C preveda che l'operazione possa essere ripetuta
+per un numero arbitrario di caratteri, alle implementazioni è richiesto
+di garantire solo un livello; questo è quello che fa la \acr{glibc}, che
+richiede che avvenga un'altra operazione fra due \func{ungetc}
+successive.
+
+Non è necessario che il carattere che si manda indietro sia l'ultimo che
+si è letto, e non è necessario neanche avere letto nessun carattere
+prima di usare \func{ungetc}, ma di norma la funzione è intesa per
+essere usata per rimandare indietro l'ultimo carattere letto.
+Nel caso \param{c} sia un \macro{EOF} la funzione non fa nulla, e
+restituisce sempre \macro{EOF}; così si può usare \func{ungetc} anche
+con il risultato di una lettura alla fine del file.
+Se si è alla fine del file si può comunque rimandare indietro un
+carattere, il flag di end-of-file verrà automaticamente cancellato
+perché c'è un nuovo carattere disponibile che potrà essere riletto
+successivamente.
+Infine si tenga presente che \func{ungetc} non altera il contenuto del
+file, ma opera esclusivamente sul buffer interno. Se si esegue una
+qualunque delle operazioni di riposizionamento (vedi
+\secref{sec:file_fseek}) i caratteri rimandati indietro vengono
+scartati.
\subsection{Input/output di linea}
La terza ed ultima modalità di input/output non formattato è quello di
linea, in cui legge o scrive una riga alla volta; questa è una modalità
-molto usata, ma che presenta le caratteristiche più controverse.
+molto usata per l'I/O da terminale, ma che presenta le caratteristiche
+più controverse.
-Le funzioni per leggere una linea sono sostazialmente due, \func{gets} e
-\func{fgets}, i rispettivi prototipi sono:
+Le funzioni per leggere una linea sono sostanzialmente due, \func{gets} e
+\func{fgets}, i cui rispettivi prototipi sono:
\begin{functions}
\headdecl{stdio.h}
Gli stream possono essere usati in applicazioni multi-thread allo stesso
modo in cui sono usati nelle applicazioni normali, ma si deve essere
-consapovoli delle possibili complicazioni anche quando non si usano i
+consapevoli delle possibili complicazioni anche quando non si usano i
thread, dato che l'implementazione delle librerie è influenzata
pesantemente dalle richieste necessarie per garantirne l'uso coi thread.