\subsection{I \textit{file stream}}
\label{sec:file_stream}
+\index{file!stream|(}
Come più volte ribadito, l'interfaccia dei file descriptor è un'interfaccia di
basso livello, che non provvede nessuna forma di formattazione dei dati e
nessuna forma di bufferizzazione per ottimizzare le operazioni di I/O.
(sui quali sono basati), ed in particolare continua a valere quanto visto in
\secref{sec:file_sharing} a proposito dell'accesso condiviso ed in
\secref{sec:file_access_control} per il controllo di accesso.
+\index{file!stream|)}
\subsection{Gli oggetti \ctyp{FILE}}
specificato da \param{stream}, se questo è già aperto prima lo chiude.
\bodydesc{Le funzioni ritornano un puntatore valido in caso di successo e
- \macro{NULL} in caso di errore, in tal caso \var{errno} assumerà il valore
+ \val{NULL} in caso di errore, in tal caso \var{errno} assumerà il valore
ricevuto dalla funzione sottostante di cui è fallita l'esecuzione.
Gli errori pertanto possono essere quelli di \code{malloc} per tutte
preventivamente chiuso.
Infine \func{fdopen} viene usata per associare uno stream ad un file
-descriptor esistente ottenuto tramite una altra funzione (ad esempio con
-una \func{open}, una \func{dup}, o una \func{pipe}) e serve quando si
-vogliono usare gli stream con file come le fifo o i socket, che non
+descriptor esistente ottenuto tramite una altra funzione (ad esempio con una
+\func{open}, una \func{dup}, o una \func{pipe}) e serve quando si vogliono
+usare gli stream con file come le fifo o i socket\index{socket}, che non
possono essere aperti con le funzioni delle librerie standard del C.
\begin{table}[htb]
indicate dopo aver specificato il \param{mode} con uno dei valori di
\tabref{tab:file_fopen_mode}. L'uso del carattere \texttt{x} serve per
evitare di sovrascrivere un file già esistente (è analoga all'uso
-dell'opzione \macro{O\_EXCL} in \func{open}), se il file specificato già
+dell'opzione \const{O\_EXCL} in \func{open}), se il file specificato già
esiste e si aggiunge questo carattere a \param{mode} la \func{fopen}
fallisce.
I nuovi file saranno creati secondo quanto visto in
\secref{sec:file_ownership} ed avranno i permessi di accesso impostati al
-valore \macro{S\_IRUSR|S\_IWUSR|S\_IRGRP|S\_IWGRP|S\_IROTH|S\_IWOTH} (pari a
+valore \code{S\_IRUSR|S\_IWUSR|S\_IRGRP|S\_IWGRP|S\_IROTH|S\_IWOTH} (pari a
\var{0666}) modificato secondo il valore di \acr{umask} per il processo (si
veda \secref{sec:file_umask}).
\begin{prototype}{stdio.h}{int fclose(FILE *stream)}
Chiude lo stream \param{stream}.
- \bodydesc{Restituisce 0 in caso di successo e \macro{EOF} in caso di errore,
- nel qual caso imposta \var{errno} a \macro{EBADF} se il file descriptor
+ \bodydesc{Restituisce 0 in caso di successo e \val{EOF} in caso di errore,
+ nel qual caso imposta \var{errno} a \errval{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}).}
\begin{prototype}{stdio.h}{int fcloseall(void)}
Chiude tutti gli stream.
- \bodydesc{Restituisce 0 se non ci sono errori ed \macro{EOF} altrimenti.}
+ \bodydesc{Restituisce 0 se non ci sono errori ed \val{EOF} altrimenti.}
\end{prototype}
\noindent la funzione esegue lo scarico dei dati bufferizzati in uscita
e scarta quelli in ingresso, chiudendo tutti i file. Questa funzione è
raggiungimento della fine del file è considerato un errore, e viene
notificato come tale dai valori di uscita delle varie funzioni. Nella
maggior parte dei casi questo avviene con la restituzione del valore
-intero (di tipo \ctyp{int}) \macro{EOF}\footnote{la costante deve essere
+intero (di tipo \ctyp{int}) \val{EOF}\footnote{la costante deve essere
negativa, le \acr{glibc} usano -1, altre implementazioni possono avere
valori diversi.} definito anch'esso nell'header \file{stdlib.h}.
\bodydesc{Tutte queste funzioni leggono un byte alla volta, che viene
restituito come intero; in caso di errore o fine del file il valore
- di ritorno è \macro{EOF}.}
+ di ritorno è \val{EOF}.}
\end{functions}
A parte \func{getchar}, che si usa in genere per leggere un carattere da
\funcdecl{wint\_t getwchar(void)} Equivalente a \code{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}.}
+ caso di errore o fine del file il valore di ritorno è \const{WEOF}.}
\end{functions}
Per scrivere un carattere si possono usare tre funzioni analoghe alle
\bodydesc{Le funzioni scrivono sempre un carattere alla volta, il cui
valore viene restituito in caso di successo; in caso di errore o
- fine del file il valore di ritorno è \macro{EOF}.}
+ fine del file il valore di ritorno è \val{EOF}.}
\end{functions}
Tutte queste funzioni scrivono sempre un byte alla volta, anche se
prendono come parametro un \ctyp{int} (che pertanto deve essere ottenuto
con un cast da un \ctyp{unsigned char}). Anche il valore di ritorno è
sempre un intero; in caso di errore o fine del file il valore di ritorno
-è \macro{EOF}.
+è \val{EOF}.
Come nel caso dell'I/O binario le \acr{glibc} provvedono per ciascuna
delle funzioni precedenti, come estensione GNU, una seconda funzione, il
\funcdecl{int putw(int w, FILE *stream)} Scrive la parola \param{w} su
\param{stream}.
- \bodydesc{Le funzioni restituiscono la parola \param{w}, o \macro{EOF}
+ \bodydesc{Le funzioni restituiscono la parola \param{w}, o \val{EOF}
in caso di errore o di fine del file.}
\end{functions}
\noindent l'uso di queste funzioni è deprecato in favore dell'uso di
\func{fread} e \func{fwrite}, in quanto non è possibile distinguere il
-valore -1 da una condizione di errore che restituisce \macro{EOF}.
+valore -1 da una condizione di errore che restituisce \val{EOF}.
Uno degli usi più frequenti dell'input/output a caratteri è nei programmi di
\textit{parsing} in cui si analizza il testo; in questo contesto diventa utile
char}, sullo stream \param{stream}.
\bodydesc{La funzione ritorna \param{c} in caso di successo e
- \macro{EOF} in caso di errore.}
+ \val{EOF} in caso di errore.}
\end{prototype}
\noindent benché lo standard ANSI C preveda che l'operazione possa
essere ripetuta per un numero arbitrario di caratteri, alle
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
+Nel caso \param{c} sia un \val{EOF} la funzione non fa nulla, e
+restituisce sempre \val{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
massimo di \param{size} byte.
\bodydesc{Le funzioni restituiscono l'indirizzo \param{string} in caso
- di successo o \macro{NULL} in caso di errore.}
+ di successo o \val{NULL} in caso di errore.}
\end{functions}
Entrambe le funzioni effettuano la lettura (dal file specificato \func{fgets},
capo della tastiera), ma \func{gets} sostituisce \verb|'\n'| con uno zero,
mentre \func{fgets} aggiunge uno zero dopo il \textit{newline}, che resta
dentro la stringa. Se la lettura incontra la fine del file (o c'è un errore)
-viene restituito un \macro{NULL}, ed il buffer \param{buf} non viene toccato.
+viene restituito un \val{NULL}, ed il buffer \param{buf} non viene toccato.
L'uso di \func{gets} è deprecato e deve essere assolutamente evitato; la
funzione infatti non controlla il numero di byte letti, per cui nel caso la
stringa letta superi le dimensioni del buffer, si avrà un \textit{buffer
\param{stream} la linea \param{string}.
\bodydesc{Le funzioni restituiscono un valore non negativo in caso di
- successo o \macro{EOF} in caso di errore.}
+ successo o \val{EOF} in caso di errore.}
\end{functions}
Dato che in questo caso si scrivono i dati in uscita \func{puts} non ha i
linea \param{ws} di caratteri estesi sul file \param{stream}.
\bodydesc{Le funzioni ritornano rispettivamente \param{ws} o un numero
- non negativo in caso di successo e \macro{NULL} o \macro{EOF} in
+ non negativo in caso di successo e \val{NULL} o \val{EOF} in
caso di errore o fine del file.}
\end{functions}
\noindent il cui comportamento è identico a quello di \func{fgets} e
i valori delle variabili, secondo la tecnica spiegata in
\secref{sec:proc_var_passing}).
-Se si passa alla funzione l'indirizzo di un puntatore impostato a \macro{NULL}
+Se si passa alla funzione l'indirizzo di un puntatore impostato a \val{NULL}
e \var{*n} è zero, la funzione provvede da sola all'allocazione della memoria
necessaria a contenere la linea. In tutti i casi si ottiene dalla funzione un
puntatore all'inizio del testo della linea letta. Un esempio di codice può
\textbf{Valore} & \textbf{Significato}\\
\hline
\hline
- \cmd{\#} & Chiede la conversione in forma alternativa. \\
- \cmd{0} & La conversione è riempita con zeri alla sinistra del valore.\\
- \cmd{-} & La conversione viene allineata a sinistra sul bordo del campo.\\
- \cmd{' '}& Mette uno spazio prima di un numero con segno di valore
+ \val{\#} & Chiede la conversione in forma alternativa. \\
+ \val{0} & La conversione è riempita con zeri alla sinistra del valore.\\
+ \val{-} & La conversione viene allineata a sinistra sul bordo del campo.\\
+ \val{' '}& Mette uno spazio prima di un numero con segno di valore
positivo\\
- \cmd{+} & Mette sempre il segno ($+$ o $-$) prima di un numero.\\
+ \val{+} & Mette sempre il segno ($+$ o $-$) prima di un numero.\\
\hline
\end{tabular}
\caption{I valori dei flag per il formato di \func{printf}}
% [n. parametro $] [flag] [[larghezza] [. precisione]] [tipo] conversione
\end{verbatim}
\end{center}
-in cui tutti i valori tranne il \cmd{\%} e lo specificatore di conversione
+in cui tutti i valori tranne il \val{\%} e lo specificatore di conversione
sono opzionali (e per questo sono indicati fra parentesi quadre); si possono
usare più elementi opzionali, nel qual caso devono essere specificati in
questo ordine:
\begin{itemize*}
-\item uno specificatore del parametro da usare (terminato da un \cmd{\$}),
+\item uno specificatore del parametro da usare (terminato da un \val{\$}),
\item uno o più flag (i cui valori possibili sono riassunti in
\tabref{tab:file_format_flag}) che controllano il formato di stampa della
conversione,
parametri dovrà essere opportunamente trattata (l'argomento è esaminato in
\secref{sec:proc_variadic}), e dopo l'esecuzione della funzione l'argomento
\param{ap} non sarà più utilizzabile (in generale dovrebbe essere eseguito un
-\macro{va\_end(ap)} ma in Linux questo non è necessario).
+\code{va\_end(ap)} ma in Linux questo non è necessario).
Come per \func{sprintf} anche per \func{vsprintf} esiste una analoga
\func{vsnprintf} che pone un limite sul numero di caratteri che vengono
\bodydesc{Le funzioni ritornano il numero di elementi assegnati. Questi
possono essere in numero inferiore a quelli specificati, ed anche zero.
Quest'ultimo valore significa che non si è trovata corrispondenza. In caso
- di errore o fine del file viene invece restituito \macro{EOF}.}
+ di errore o fine del file viene invece restituito \val{EOF}.}
\end{functions}
\noindent e come per le analoghe funzioni di scrittura esistono le relative
\func{vscanf}, \func{vfscanf} \func{vsscanf} che usano un puntatore ad una
punto prestabilito; sempre che l'operazione di riposizionamento sia supportata
dal file sottostante lo stream, quando cioè si ha a che fare con quello che
viene detto un file ad \textsl{accesso casuale}.\footnote{dato che in un
- sistema Unix esistono vari tipi di file, come le fifo ed i dispositivi, non
- è scontato che questo sia sempre vero.}
+ sistema Unix esistono vari tipi di file, come le fifo ed i file di
+ dispositivo\index{file!di dispositivo}, non è scontato che questo sia sempre
+ vero.}
In GNU/Linux ed in generale in ogni sistema unix-like la posizione nel file è
espressa da un intero positivo, rappresentato dal tipo \type{off\_t}, il
\bodydesc{Restituisce il numero del file descriptor in caso di successo, e
-1 qualora \param{stream} non sia valido, nel qual caso imposta
- \var{errno} a \macro{EBADF}.}
+ \var{errno} a \errval{EBADF}.}
\end{prototype}
\noindent ed in questo modo diventa possibile usare direttamente \func{fcntl}.
stream. In genere conviene allocarlo con \func{malloc} e disallocarlo dopo la
chiusura del file; ma fintanto che il file è usato all'interno di una
funzione, può anche essere usata una variabile automatica. In \file{stdio.h} è
-definita la macro \macro{BUFSIZ}, che indica le dimensioni generiche del
+definita la macro \const{BUFSIZ}, che indica le dimensioni generiche del
buffer di uno stream; queste vengono usate dalla funzione \func{setbuf}. Non
è detto però che tale dimensione corrisponda sempre al valore ottimale (che
può variare a seconda del dispositivo).
\textbf{Valore} & \textbf{Modalità} \\
\hline
\hline
- \macro{\_IONBF} & \textit{unbuffered}\\
- \macro{\_IOLBF} & \textit{line buffered}\\
- \macro{\_IOFBF} & \textit{fully buffered}\\
+ \const{\_IONBF} & \textit{unbuffered}\\
+ \const{\_IOLBF} & \textit{line buffered}\\
+ \const{\_IOFBF} & \textit{fully buffered}\\
\hline
\end{tabular}
\caption{Valori del parametro \param{mode} di \func{setvbuf}
\end{table}
Per evitare che \func{setvbuf} imposti il buffer basta passare un valore
-\macro{NULL} per \param{buf} e la funzione ignorerà il parametro \param{size}
+\val{NULL} per \param{buf} e la funzione ignorerà il parametro \param{size}
usando il buffer allocato automaticamente dal sistema. Si potrà comunque
modificare la modalità di bufferizzazione, passando in \param{mode} uno degli
opportuni valori elencati in \tabref{tab:file_stream_buf_mode}. Qualora si
\headdecl{stdio.h}
\funcdecl{void setbuf(FILE *stream, char *buf)} Disabilita la
- bufferizzazione se \param{buf} è \macro{NULL}, altrimenti usa \param{buf}
- come buffer di dimensione \macro{BUFSIZ} in modalità \textit{fully buffered}.
+ bufferizzazione se \param{buf} è \val{NULL}, altrimenti usa \param{buf}
+ come buffer di dimensione \const{BUFSIZ} in modalità \textit{fully buffered}.
\funcdecl{void setbuffer(FILE *stream, char *buf, size\_t size)} Disabilita
- la bufferizzazione se \param{buf} è \macro{NULL}, altrimenti usa \param{buf}
+ la bufferizzazione se \param{buf} è \val{NULL}, altrimenti usa \param{buf}
come buffer di dimensione \param{size} in modalità \textit{fully buffered}.
\funcdecl{void setlinebuf(FILE *stream)} Pone lo stream in modalità
Forza la scrittura di tutti i dati bufferizzati dello stream \param{stream}.
- \bodydesc{Restituisce zero in caso di successo, ed \macro{EOF} in caso di
- errore, impostando \var{errno} a \macro{EBADF} se \param{stream} non è
+ \bodydesc{Restituisce zero in caso di successo, ed \val{EOF} in caso di
+ errore, impostando \var{errno} a \errval{EBADF} se \param{stream} non è
aperto o non è aperto in scrittura, o ad uno degli errori di
\func{write}.}
\end{prototype}
\macro{\_SVID\_SOURCE} o \macro{\_GNU\_SOURCE}.} che non effettua il blocco
dello stream.
-Se \param{stream} è \macro{NULL} lo scarico dei dati è forzato per tutti gli
+Se \param{stream} è \val{NULL} lo scarico dei dati è forzato per tutti gli
stream aperti. Esistono però circostanze, ad esempio quando si vuole essere
sicuri che sia stato eseguito tutto l'output su terminale, in cui serve poter
effettuare lo scarico dei dati solo per gli stream in modalità line buffered;
Cancella i buffer di input e di output dello stream \param{stream}.
- \bodydesc{Restituisce zero in caso di successo, ed \macro{EOF} in caso di
+ \bodydesc{Restituisce zero in caso di successo, ed \val{EOF} in caso di
errore.}
\end{prototype}
all'acquisizione implicita del blocco sullo stream.
\bodydesc{Restituisce lo stato di locking interno dello stream con uno dei
- valori \macro{FSETLOCKING\_INTERNAL} o \macro{FSETLOCKING\_BYCALLER}.}
+ valori \const{FSETLOCKING\_INTERNAL} o \const{FSETLOCKING\_BYCALLER}.}
\end{prototype}
La funzione imposta o legge lo stato della modalità di operazione di uno stream
nei confronti del locking a seconda del valore specificato con \param{type},
che può essere uno dei seguenti:
\begin{basedescript}{\desclabelwidth{4.0cm}}
-\item[\macro{FSETLOCKING\_INTERNAL}] Lo stream userà da ora in poi il blocco
+\item[\const{FSETLOCKING\_INTERNAL}] Lo stream userà da ora in poi il blocco
implicito predefinito.
-\item[\macro{FSETLOCKING\_BYCALLER}] Al ritorno della funzione sarà l'utente a
+\item[\const{FSETLOCKING\_BYCALLER}] Al ritorno della funzione sarà l'utente a
dover gestire da solo il locking dello stream.
-\item[\macro{FSETLOCKING\_QUERY}] Restituisce lo stato corrente della modalità
+\item[\const{FSETLOCKING\_QUERY}] Restituisce lo stato corrente della modalità
di blocco dello stream.
\end{basedescript}
projects / gapil.git / blobdiff