[successivo] [precedente] [inizio] [fine] [indice generale] [indice ridotto] [indice analitico] [home] [volume] [parte]


Capitolo 631.   C: «stdio.h» per la gestione dei file e degli errori

Macro-variabile Significato mnemonico Descrizione
_IOFBF
input output fully buffered Indica simbolicamente la richiesta di utilizzo di una memoria tampone a blocchi.
_IOLBF
input output line buffered Indica simbolicamente la richiesta di utilizzo di una memoria tampone gestita a righe di testo.
_IONBF
input output with no buffering Indica simbolicamente la richiesta di non utilizzare alcuna memoria tampone.
BUFSIZE
buffer size Rappresenta la dimensione predefinita della memoria tampone.
EOF
end of file È un numero intero di tipo int, negativo, che rappresenta il raggiungimento della fine del file. È in pratica ciò che si ottiene leggendo oltre la fine del file.
FOPEN_MAX
file open max Il numero di file che un processo elaborativo può aprire simultaneamente, in base alle limitazioni poste dal sistema operativo.
FILENAME_MAX
La dimensione di un array di elementi char, tale da essere abbastanza grande da contenere il nome del file più lungo (incluse le eventuali sequenze multibyte) che il sistema consenta di gestire.
L_tmpnam
temporary name La dimensione di un array di elementi char, tale da essere abbastanza grande da contenere il nome di un file temporaneo generato dalla funzione tmpnam().
SEEK_CUR
seek current Indica di eseguire un posizionamento a partire dalla posizione corrente del file.
SEEK_END
Indica di eseguire un posizionamento a partire dalla fine di un file.
SEEK_SET
Indica di eseguire un posizionamento a partire dall'inizio di un file.
TMP_MAX
Rappresenta la quantità massima di nomi di file differenti che possono essere generati dalla funzione tmpnam().
Modalità di accesso ai file Mnemonico Descrizione
r
read Accesso in sola lettura di un file di testo.
w
write Accesso a un file di testo in scrittura, che implica la creazione del file all'apertura, ovvero il suo troncamento a zero, se esiste già.
a
append Accesso a un file di testo in aggiunta, che implica la creazione del file all'apertura, ovvero la sua estensione se esiste già.
rb
wb
ab
binary Accesso in lettura, scrittura o aggiunta, ma di tipo binario.
r+
w+
a+
update Accesso a un file di testo in lettura, scrittura o aggiunta, assieme alla modalità di aggiornamento. In pratica, con la lettura è consentita anche la scrittura; con la scrittura e l'aggiunta è consentita anche la rilettura.
rb+|r+b
wb+|w+b
ab+|a+b
Accesso a un file binario in lettura, scrittura o aggiunta, assieme alla modalità di aggiornamento. In pratica, con la lettura è consentita anche la scrittura; con la scrittura e l'aggiunta è consentita anche la rilettura. Si può osservare che il segno + può essere messo indifferentemente in mezzo o alla fine.
Funzione Descrizione
int remove (const char *filename);
Cancella il file il cui nome viene fornito come argomento. Il nome del file va espresso secondo le convenzioni del sistema operativo. Restituisce zero se l'operazione ha successo, altrimenti un valore differente.
int rename (const char *old,
            const char *new);
Cambia il nome del file indicato come primo argomento, in modo che assuma quello del secondo argomento. Se l'operazione avviene con successo restituisce zero, altrimenti produce un valore differente.
FILE *tmpfile (void);
Crea e apre un file temporaneo binario in aggiornamento (wb+), restituendone il puntatore. Se il file temporaneo non può essere creato, la funzione restituisce il puntatore nullo.
char *tmpnam (char *s);
Genera il nome di un file che può essere usato come file temporaneo. La funzione richiede come argomento un array di almeno L_tmpnam caratteri, da usare per scriverci il nome e per restituirne il puntatore. Se alla funzione viene passato il puntatore nullo, allora questa usa un'area di memoria statica che viene sovrascritta a ogni chiamata successiva della funzione stessa. Se la funzione non può eseguire il suo lavoro, restituisce il puntatore nullo.
FILE *fopen (const char *restrict filename,
             const char *restrict io_mode);
Apre il file indicato come primo argomento, secondo la modalità espressa dalla stringa che costituisce il secondo argomento, restituendo il puntatore che ne rappresenta il flusso aperto. Se l'operazione fallisce la funzione restituisce il puntatore nullo e aggiorna il valore della variabile globale errno.
FILE *freopen (const char *restrict filename,
               const char *restrict io_mode,
               FILE *restrict stream);
Apre il file indicato come primo argomento, secondo la modalità espressa dalla stringa che costituisce il secondo argomento, utilizzando il flusso di file individuato dal puntatore che costituisce l'ultimo argomento, restituendo lo stesso puntatore. Se il puntatore indicato come ultimo argomento riguarda un flusso di file ancora aperto, questo viene chiuso e quindi riaperto. Se l'operazione fallisce la funzione restituisce il puntatore nullo e aggiorna il valore della variabile globale errno. Lo scopo di questa funzione è quello di ridirigere i flussi di file, associando file differenti.
int fclose (FILE *stream);
Chiude il flusso di file individuato dal puntatore che costituisce l'argomento della funzione. La funzione restituisce il valore zero se l'operazione ha successo, altrimenti produce il valore corrispondente alla macro-variabile EOF. Va sottolineato che un flusso già chiuso non deve essere chiuso nuovamente, perché in tal caso l'effetto che se ne produce è imprecisato.
int setvbuf (FILE *restrict stream,
             char *restrict buffer,
             int buf_mode,
             size_t size);
Attribuisce una memoria tampone a un file che è appena stato aperto e per il quale non è ancora stato eseguito alcun accesso. Il primo argomento della funzione è il puntatore al flusso relativo e il secondo è il puntatore all'inizio dell'array di caratteri da usare come memoria tampone. Se al posto del riferimento alla memoria tampone si indica un puntatore nullo, si intende che la funzione debba allocare automaticamente lo spazio necessario; se invece l'array viene fornito, è evidente che deve rimanere disponibile per tutto il tempo in cui il flusso rimane aperto.
Il terzo argomento atteso dalla funzione è un numero che esprime la modalità di funzionamento della memoria tampone. Questo numero viene fornito attraverso l'indicazione di una tra le macro-variabili _IOFBF, _IOLBF e _IONBF. Il quarto argomento indica la dimensione dell'array da usare come memoria tampone: se l'array viene fornito effettivamente, si tratta della dimensione che può essere utilizzata; altrimenti è la dimensione richiesta per l'allocazione automatica.
La funzione restituisce zero se l'operazione richiesta è eseguita con successo; diversamente restituisce un valore differente.
void setbuf (FILE *restrict stream,
             char *restrict buffer);
Si tratta di una versione semplificata di setvbuf() che non restituisce alcun valore, che prevede implicitamente una modalità di gestione completa della memoria tampone (_IOFBF), che richiede implicitamente un array di BUFSIZ elementi. Anche in questo caso, se l'argomento corrispondente al parametro buffer è un puntatore nullo, l'allocazione avviene in modo automatico.
int fflush (FILE *stream);
Scarica la memoria tampone del flusso di file indicato, procedendo così alla memorizzazione dei dati rimasti in sospeso. Restituisce zero se l'operazione viene completata con successo, altrimenti restituisce il valore corrispondente alla macro-variabile EOF.
int fgetc (FILE *stream);
int getc (FILE *stream);
Legge un carattere (senza segno) dal flusso di file indicato come argomento e ne restituisce il valore numerico (positivo). Se l'operazione fallisce, la funzione restituisce il valore corrispondente alla macro-variabile EOF. Tradizionalmente, fgetc() è sempre una funzione, mentre getc() potrebbe essere una macro-istruzione che valuta anche più volte l'espressione che costituisce l'argomento.
int ungetc (int c, FILE *stream);
Rimanda indietro il carattere c nel flusso di file stream; in altri termini dovrebbe annullare l'effetto dell'ultima chiamata a una funzione fgetc() o getc().
int fputc (int c, FILE *stream);
int putc (int c, FILE *stream);
Scrive un carattere, rappresentato dal primo argomento, nel flusso di file indicato come secondo argomento, restituendo lo stesso valore del carattere scritto, se l'operazione si conclude con successo, oppure il valore corrispondente a EOF se l'operazione fallisce. Tradizionalmente, fputc() è sempre una funzione, mentre putc() potrebbe essere una macro-istruzione che valuta anche più volte le espressioni che costituiscono gli argomenti.
int putchar (int c);
Scrive un carattere, rappresentato dall'argomento, nello standard output, restituendo lo stesso valore del carattere scritto, se l'operazione si conclude con successo, oppure il valore corrispondente a EOF se l'operazione fallisce. Tradizionalmente si tratta di una macro-istruzione che valuta anche più volte l'espressione che costituisce l'argomento.
char *fgets (char *restrict s,
             int n,
             FILE *restrict stream);
Legge al massimo n-1 caratteri (elementi char) attraverso il flusso di file stream, copiandoli in memoria a partire dall'indirizzo s e aggiungendo alla fine il carattere nullo di terminazione delle stringhe. La lettura si esaurisce prima di n-1 caratteri se viene incontrato il codice di interruzione di riga, il quale viene rappresentato nella stringa a cui punta s, ovvero se si raggiunge la fine del file. In ogni caso, la stringa s viene terminata correttamente con il carattere nullo.
La funzione restituisce la stringa s se la lettura avviene con successo, ovvero se ha prodotto almeno un carattere; altrimenti, il contenuto dell'array a cui punta s non viene modificato e la funzione restituisce il puntatore nullo. Se si creano errori imprevisti, la funzione potrebbe restituire il puntatore nullo, ma senza garantire che l'array s sia rimasto intatto.
int fputs (const char *restrict s,
           FILE *restrict stream);
Copia la stringa a cui punta s nel file rappresentato dal flusso di file stream. La copia della stringa avviene escludendo però il carattere nullo di terminazione. Va osservato che questa funzione, pur essendo contrapposta evidentemente a fgets(), non conclude la riga del file, ovvero, non aggiunge il codice di interruzione di riga. Per ottenere la conclusione della riga di un file di testo, occorre inserire nella stringa, espressamente, il carattere \n.
La funzione restituisce il valore rappresentato da EOF se l'operazione di scrittura produce un errore; altrimenti restituisce un valore positivo qualunque.
char *gets (char *s);
Legge una riga dallo standard input, copiandola in memoria a partire dall'indirizzo s e aggiungendo alla fine il carattere nullo di terminazione delle stringhe. Per il resto, il funzionamento è conforme a quello di fgets().
int puts (const char *s);
Copia la stringa a cui punta s nello standard output, aggiungendo in coda il codice di interruzione di riga. Per il resto, il funzionamento è analogo a quello di fputs().
size_t fread (void *restrict ptr,
              size_t size,
              size_t nmemb,
              FILE *restrict stream);
Legge dal flusso di file stream, nmemb blocchi da size byte, copiando questi dati in memoria a partire dall'indirizzo ptr. Restituisce la quantità di blocchi da size byte che sono stati copiati con successo; pertanto, se questo valore è inferiore a nmemb, si è verificato un problema.
size_t fwrite (const void *restrict ptr,
               size_t size,
               size_t nmemb,
               FILE *restrict stream);
Scrive nel flusso di file stream, nmemb blocchi da size byte, leggendo questi dati dalla memoria a partire dall'indirizzo ptr. Restituisce la quantità di blocchi da size byte che sono stati copiati con successo; pertanto, se questo valore è inferiore a nmemb, si è verificato un problema.
int fseek (FILE *stream,
           long int offset,
           int whence);
Sposta la posizione corrente relativa al flusso di file stream (associato preferibilmente a un file binario), nella nuova posizione determinata dai parametri whence e offset. Il parametro whence viene fornito attraverso una macro-variabile che può essere SEEK_SET, SEEK_CUR o SEEK_END, indicando rispettivamente l'inizio del file, la posizione corrente o la fine del file. Dalla posizione indicata dal parametro whence viene aggiunta, algebricamente, la quantità di byte indicata dal parametro offset. La funzione restituisce zero se può eseguire l'operazione, altrimenti dà un risultato diverso.
long int ftell (FILE *stream);
Restituisce la posizione corrente del flusso di file indicato come argomento. Questo valore può essere usato con fseek(), al posto dello scostamento (il parametro offset), indicando come posizione di riferimento l'inizio del file, ovvero SEEK_SET. Se la funzione non riesce a fornire la posizione, restituisce il valore -1 (tradotto in long int) e annota il fatto nella variabile errno.
void rewind (FILE *stream);
Riposiziona il flusso di file all'inizio. In pratica è come utilizzare la funzione fseek() specificando uno scostamento pari a zero a partire da SEEK_SET, ignorando il valore restituito.
int fgetpos (FILE *restrict stream,
             fpos_t *restrict pos);
Memorizza nella variabile a cui punta il parametro pos le informazioni sulla posizione corrente del file, assieme allo stato di interpretazione relativo alle sequenze multibyte. Restituisce zero se l'operazione è stata compiuta con successo, altrimenti dà un altro valore
int fsetpos (FILE *stream,
             const fpos_t *pos);
Utilizza la variabile a cui punta pos per ripristinare la posizione memorizzata, assieme allo stato di avanzamento dell'interpretazione di una sequenza multibyte. Restituisce zero se l'operazione è stata compiuta con successo, altrimenti dà un altro valore e aggiorna la variabile errno.
void clearerr (FILE *stream);
Azzera gli indicatori di errore e di fine file per il flusso di file indicato come argomento, senza restituire alcunché.
int feof (FILE *stream);
Controlla lo stato dell'indicatore di fine file per il flusso di file indicato. Se questo non è attivo restituisce zero, altrimenti restituisce un valore diverso da zero.
int ferror (FILE *stream);
Controlla lo stato dell'indicatore di errore per il flusso di file indicato. Se questo non è attivo restituisce zero, altrimenti restituisce un valore diverso da zero.
void perror (const char *s);
Prende in considerazione la variabile errno e cerca di tradurla in un messaggio testuale da emettere attraverso lo standard error (con tanto di terminazione della riga, in modo da riposizionare a capo il cursore). Se il parametro s corrisponde a una stringa non vuota, il testo di questa viene posto anteriormente al messaggio, separandolo con due punti e uno spazio (). Il contenuto del messaggio è lo stesso che si otterrebbe con la funzione strerror(), fornendo come argomento la variabile errno.

Appunti di informatica libera 2008 --- Copyright © 2000-2008 Daniele Giacomini -- <appunti2 (ad) gmail·com>


Dovrebbe essere possibile fare riferimento a questa pagina anche con il nome c_171_stdio_h_187_per_la_gestione_dei_file_e_degli_errori.htm

[successivo] [precedente] [inizio] [fine] [indice generale] [indice ridotto] [indice analitico] [home]

Valid ISO-HTML!

CSS validator!

Gjlg Metamotore e Web Directory