X-Git-Url: https://gapil.gnulinux.it/gitweb/?p=gapil.git;a=blobdiff_plain;f=filestd.tex;h=670e55b28db3a1709d4652d863b41a147dfc3e30;hp=80c641b46409c81788204e91289292883a32a42a;hb=5a59e67204ff436dceb6a13ed39e876aea3945a8;hpb=76c815519021c83247a87d9f4318fc4aaa533f56;ds=sidebyside diff --git a/filestd.tex b/filestd.tex index 80c641b..670e55b 100644 --- a/filestd.tex +++ b/filestd.tex @@ -231,7 +231,7 @@ Le funzioni che si possono usare per aprire uno stream sono solo tre: 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 @@ -304,7 +304,7 @@ Le \acr{glibc} supportano alcune estensioni, queste devono essere sempre 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. @@ -323,7 +323,7 @@ non viene duplicato e verr 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}). @@ -350,8 +350,8 @@ Uno stream viene chiuso con la funzione \func{fclose} il cui prototipo \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 \const{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}).} @@ -366,11 +366,11 @@ una \func{sync} (vedi \secref{sec:file_sync}). Linux supporta anche una altra funzione, \func{fcloseall}, come estensione GNU implementata dalle \acr{glibc}, accessibile avendo definito -\macro{\_GNU\_SOURCE}, il suo prototipo è: +\const{\_GNU\_SOURCE}, il suo prototipo è: \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 è @@ -402,7 +402,7 @@ A differenza dell'interfaccia dei file descriptor, con gli stream il 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}. @@ -596,7 +596,7 @@ rispettivi prototipi sono: \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 @@ -636,7 +636,7 @@ byte restituiscono un carattere in formato esteso (cio \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 @@ -655,14 +655,14 @@ precedenti usate per leggere: \func{putc}, \func{fputc} e \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 @@ -680,12 +680,12 @@ loro prototipi sono: \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 @@ -703,7 +703,7 @@ lettura si chiama \func{ungetc} ed il suo prototipo 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 @@ -716,8 +716,8 @@ si 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 @@ -754,7 +754,7 @@ prototipi sono: 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}, @@ -763,7 +763,7 @@ carattere \textit{newline}, \verb|'\n'|, quello mappato sul tasto di ritorno a 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 @@ -803,7 +803,7 @@ rispettivi prototipi sono: \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 @@ -826,7 +826,7 @@ per leggere e scrivere caratteri estesi, i loro prototipi sono: 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 @@ -856,7 +856,7 @@ che eccede le dimensioni del buffer. Per questo motivo le \acr{glibc} prevedono, come estensione GNU, due nuove funzioni per la gestione dell'input/output di linea, il cui uso permette di risolvere questi problemi. L'uso di queste funzioni deve -essere attivato definendo la macro \macro{\_GNU\_SOURCE} prima di +essere attivato definendo la macro \const{\_GNU\_SOURCE} prima di includere \file{stdio.h}. La prima delle due, \func{getline}, serve per leggere una linea terminata da un newline esattamente allo stesso modo di \func{fgets}, il suo prototipo è: @@ -887,7 +887,7 @@ usati dei \textit{value result argument}, passando dei puntatori anzich 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ò @@ -1024,12 +1024,12 @@ direttiva, ed uno degli specificatori di conversione (riportati in \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}} @@ -1044,12 +1044,12 @@ generale essa % [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, @@ -1125,7 +1125,7 @@ tramite il parametro \param{ap}. Per poter far questo ovviamente la lista dei 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 @@ -1140,7 +1140,7 @@ scritti sulla stringa di destinazione: Per eliminare alla radice questi problemi, le \acr{glibc} supportano una specifica estensione GNU che alloca dinamicamente tutto lo spazio necessario; -l'estensione si attiva al solito definendo \macro{\_GNU\_SOURCE}, le due +l'estensione si attiva al solito definendo \const{\_GNU\_SOURCE}, le due funzioni sono: \begin{functions} \headdecl{stdio.h} @@ -1189,7 +1189,7 @@ famiglia \func{scanf}; fra queste le tre pi \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 @@ -1339,7 +1339,7 @@ il prototipo della funzione \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 \const{EBADF}.} \end{prototype} \noindent ed in questo modo diventa possibile usare direttamente \func{fcntl}. @@ -1423,7 +1423,7 @@ stato allocato e rimanere disponibile per tutto il tempo in cui si opera sullo 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). @@ -1445,9 +1445,9 @@ coincidano con quelle su cui viene effettuato l'I/O. \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} @@ -1456,7 +1456,7 @@ coincidano con quelle su cui viene effettuato l'I/O. \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 @@ -1470,11 +1470,11 @@ e \func{setlinebuf}; i loro prototipi sono: \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à @@ -1503,17 +1503,17 @@ scelta, si pu 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 \const{EBADF} se \param{stream} non è aperto o non è aperto in scrittura, o ad uno degli errori di \func{write}.} \end{prototype} \noindent anche di questa funzione esiste una analoga -\func{fflush\_unlocked}\footnote{accessibile definendo \macro{\_BSD\_SOURCE} o - \macro{\_SVID\_SOURCE} o \macro{\_GNU\_SOURCE}.} che non effettua il blocco +\func{fflush\_unlocked}\footnote{accessibile definendo \const{\_BSD\_SOURCE} o + \const{\_SVID\_SOURCE} o \const{\_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; @@ -1535,7 +1535,7 @@ pendente; per questo si pu 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} @@ -1565,7 +1565,7 @@ Ci sono comunque situazioni in cui questo non basta, come quando un thread necessita di compiere più di una operazione sullo stream atomicamente, per questo motivo le librerie provvedono anche delle funzioni che permettono la gestione esplicita dei blocchi sugli stream; queste funzioni sono disponibili -definendo \macro{\_POSIX\_THREAD\_SAFE\_FUNCTIONS} ed i loro prototipi sono: +definendo \const{\_POSIX\_THREAD\_SAFE\_FUNCTIONS} ed i loro prototipi sono: \begin{functions} \headdecl{stdio.h} @@ -1608,18 +1608,18 @@ prototipo 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}