C/Appendice/Librerie standard/stdio.h

stdio.h, che sta per "standard input-output header", è l'header file che contiene definizioni di macro, costanti e dichiarazioni di funzioni e tipi usati per le varie operazioni di input/output.

Tipi di dati

FILE

Struttura contenente le informazioni su un file (od in generale uno stream), necessarie per eseguire su di esso le operazioni di input/output, come ad esempio:

• la posizione attuale nello stream
• un indicatore di fine file
• un indicatore d'errore
• un puntatore al buffer dello stream, se applicabile

Un puntatore a questa struttura è richiesto come parametro da tutte le funzioni di gestione dell'input/output da file (cioè le funzioni della libreria stdio che iniziano con la lettera f)

fpos_t

Un tipo scalare capace di identificare univocamente la posizione di ogni byte in un file.

size_t

Un tipo intero che è il tipo del valore restituito dall'operatore sizeof.

Costanti

EOF

End Of File. Un numero intero negativo di tipo int usato per indicare la condizione di "raggiunta la fine file".

BUFSIZ

Un intero indicante la dimensione del buffer usato dalla funzione setbuf().

FILENAME_MAX

La dimensione di un array di char grande abbastanza da contenere il nome di un qualsiasi file gestibile su una particolare architettura.

FOPEN_MAX

La dimensione di un array di char grande abbastanza da contenere il nome di un qualsiasi file gestibile su una particolare architettura.

Valore: intero >= 8.

_IOFBF

I/O fully buffered, cioè "I/O completamente bufferizzato". Un intero che può essere passato alla funzione setvbuf() per richiedere che uno stream sia bufferizzato a blocchi.

_IOLBF

I/O line buffered, cioè "I/O bufferizzato per linee". Un intero che può essere passato alla funzione setvbuf() per richiedere che uno stream sia bufferizzato per linee.

_IONBF

I/O not buffered, cioè "I/O non bufferizzato". Un intero che può essere passato alla funzione setvbuf() per richiedere che uno stream non sia bufferizzato.

L_tmpnam

La dimensione di un array di char grande abbastanza per conservare il nome di file temporaneo generato dalla funzione tmpnam().

NULL

Una macro che espande nella costante puntatore nullo; in altre parole, una costante che rappresenta un valore che è garantito essere l'indirizzo di una posizione non valida nella memoria.

Valore: 0, 0L oppure (void*)0, a seconda delle architetture e delle implementazioni.

SEEK_CUR

Un intero che può essere passato alla funzione fseek() per richiedere un posizionamento relativo rispetto alla posizione attuale nel file.

SEEK_END

Un intero che può essere passato alla funzione fseek() per richiedere il posizionamento alla fine del file.

SEEK_SET

Un intero che può essere passato alla funzione fseek() per richiedere il posizionamento all'inizio del file.

TMP_MAX

Il massimo numero di nomi di file unici generabili dalla funzione tmpnam().

Valore: intero >= 25.

Variabili

stdin

Tipo: FILE *
Puntatore a una struttura FILE che si riferisce allo stream di standard input, generalmente la tastiera.

stdout

Tipo: FILE *
Puntatore a una struttura FILE che si riferisce allo stream di standard output, generalmente un terminale.

stderr

Tipo: FILE *
Puntatore a una struttura FILE che si riferisce allo stream di standard error, generalmente un terminale.

Funzioni

clearerr()

Dichiarazione:

void clearerr(FILE* stream);

• Parametri in ingresso:
  • FILE* stream: descrittore del file o dello stream che si vuole modificare.
• Valore di ritorno: void.

Cancella l'indicatore di fine file e quello d'errore per un dato stream.

fclose()

Dichiarazione:

int fclose(FILE* stream);

• Parametri in ingresso:
  • FILE* stream: descrittore del file o dello stream da chiudere.
• Valore di ritorno: int. Ritorna 0 in caso di successo, EOF altrimenti.

Chiude il file o lo stream specificato, eventualmente dopo aver svuotato i buffer ad esso associati (vedi fflush()).

feof()

Dichiarazione:

int feof(FILE* stream);

• Parametri in ingresso:
  • FILE* stream: descrittore del file o dello stream da controllare.
• Valore di ritorno: int. Ritorna un valore non nullo (<>0) se la fine del file è stata raggiunta, 0 altrimenti.

Controlla l'indicatore di fine file per un dato stream.

Esempio: iterare una procedura di lettura fino alla fine di un file

while(!feof(f))
{
   // lettura dati dal file f
}

ferror()

Dichiarazione:

int ferror(FILE* stream);

• Parametri in ingresso:
  • FILE* stream: descrittore del file o dello stream da controllare.
• Valore di ritorno: int. Ritorna un valore non nullo (<>0) se l'indicatore di errore è attivo, 0 altrimenti.

Controlla l'indicatore di errore per un dato stream. Se La funzione ritorna un valore diverso da zero significa che è avvenuto un errore durante una precedente operazione di input/output.

fflush()

Dichiarazione:

int fflush(FILE* stream);

• Parametri in ingresso:
  • FILE* stream: descrittore del file o dello stream. NULL indica che l'operazione va eseguita su tutti gli stream aperti..
• Valore di ritorno: int. Restituisce 0 in caso di successo, EOF altrimenti.

Svuota i buffer per un dato stream trasferendo i dati dalla memoria al supporto fisico.

La funzione fflush viene usata per prevenire perdita di dati assicurando che i dati vengano scritti sullo stream. Dovrebbe esser usata solo per stream di output; altrimenti il comportamento è indefinito. Spesso fflush è usata sullo standard output, poiché questo è bufferizzato e l'output potrebbe non esser stampato immediatamente.

Una chiamata alla funzione fclose effettua di default il flushing dello stream.

fgetpos()

Dichiarazione:

int fgetpos(FILE* stream, fpos_t* pos);

• Parametri in ingresso:
  • FILE* stream: descrittore del file o dello stream.
  • fpos_t* pos: indirizzo della variabile in cui registrare la posizione corrente.
• Valore di ritorno: int. Ritorna 0 in caso di successo, altrimenti un valore non-nullo..

Riporta la posizione corrente di lettura o scrittura nel file identificato dal primo parametro e la salva nella variabile specificata nel secondo. In caso di errore, la variabile errno viene impostata a un codice identificativo dell'errore.

fopen()

Dichiarazione:

FILE* fopen(const char* path, const char* mode);

• Parametri in ingresso:
  • const char* path: indirizzo del file da aprire.
  • const char* mode: sequenza di caratteri che identifica la modalità di apertura.
• Valore di ritorno: FILE*. ritorna un puntatore ad una struttura di tipo FILE in caso di successo, altrimenti NULL.

Apre un file identificato dal parametro path con la modalità descritta da mode e vi associa una struttura descrittiva di tipo FILE. In caso di errore, la variabile errno viene impostata a un codice identificativo dell'errore.

Il parametro mode può assumere i seguenti valori:

• "r": il file è aperto in sola lettura. La posizione è impostata all'inizio del file. Restituisce un errore nel caso in cui il file non esista.
• "r+": il file viene aperto in lettura/scrittura. La posizione è impostata all'inizio del file. Restituisce un errore nel caso in cui il file non esista.
• "w": il file viene aperto in scrittura. La posizione è impostata all'inizio del file. Se il file non esiste, viene creato; se invece il file esiste, ne viene cancellato il contenuto.
• "w+": il file viene aperto in lettura/scrittura. La posizione è impostata all'inizio del file. Se il file non esiste, viene creato; se invece il file esiste, ne viene cancellato il contenuto.
• "a": il file viene aperto in scrittura (modalità append, cioè aggiunta). La posizione è impostata alla fine del file. Se il file non esiste, viene creato; se invece il file esiste, il contenuto viene conservato inalterato ed i nuovi dati scritti vengono aggiunti dopo quelli preesistenti.
• "a+": il file viene aperto in lettura/scrittura (modalità append, cioè aggiunta). La posizione di lettura è impostata all'inizio del file, mentre la scrittura è permessa solo alla fine del file. Se il file non esiste, viene creato; se invece il file esiste, il contenuto viene conservato inalterato ed i nuovi dati scritti vengono aggiunti dopo quelli preesistenti.

Aggiungere il carattere b al parametro mode apre i file in modalità binaria, altrimenti essi vengono aperti in modalità testuale. Questo non ha alcun effetto sui sistemi compatibili POSIX (ad esempio GNU/LINUX), mentre invece è importante nei sistemi non-POSIX, come Microsoft Windows, in cui i caratteri di carriage return (codice ASCII 0x0D) vengono trasformati in carriage return + line feed (codici ASCII 0x0D + 0x0A) quando vengono scritti in un file in modalità testo.

Quando si aprono file in modalità lettura/scrittura, lo standard prevede che ogni volta che si passa da un'operazione di scrittura a una di lettura o viceversa, è necessario chiamare la funzione fflush() oppure fseek() per poter svuotare i buffer prima del cambio di modalità.

fread()

Dichiarazione:

size_t fread(void* data, size_t size, size_t count, FILE* stream);

• Parametri in ingresso:
  • void* data: indirizzo di un array in cui memorizzare i dati letti.
  • size_t size: dimensione in byte del tipo di dati da leggere.
  • size_t count: numero di elementi da leggere.
  • FILE* stream: puntatore a una struttura di tipo FILE che rappresenta lo stream da cui leggere i dati.
• Valore di ritorno: size_t. numero di elementi letti. Normalmente è uguale al parametro count, ma può essere un numero inferiore se viene incontrata la fine del file o se avviene un errore durante la lettura..

Legge dallo stream stream un numero di elementi specificato da count, ognuno della dimensione in byte size. Il numero totale di byte che la funzione tenta di leggere dallo stream è size*count. I dati letti vengono memorizzati nell'array data. La dimensione size è normalmente specificata come sizeof(tipoDati).

freopen()

Dichiarazione:

FILE* freopen(const char* path, const char* mode, FILE* stream);

• Parametri in ingresso:
  • const char* path: indirizzo del file da aprire.
  • const char* mode: sequenza di caratteri che identifica la modalità di apertura (vedi fopen()).
  • FILE* stream: puntatore allo stream da riassegnare.
• Valore di ritorno: FILE*. ritorna il parametro stream in caso di successo, altrimenti NULL.

chiude lo stream stream e associa allo stesso un nuovo file. È grossomodo equivalente a fclose() seguito da fopen(), salvo per il fatto che il parametro stream è garantito rimanere inalterato tramite la funzione freopen(). Un comune utilizzo di questa funzione è il riassegnamento degli stream standard stdin, stdout e stderr a file arbitrari.

fseek()

Dichiarazione:

int fseek(FILE* stream, long int offset, int partenza);

• Parametri in ingresso:
  • FILE* stream: puntatore allo stream.
  • long int offset: numero di byte di cui spostarsi nello stream.
  • int partenza: una delle costanti SEEK_SET, SEEK_CUR, SEEK_END, che identificano il punto di riferimento da cui iniziare a contare i byte (rispettivamente: inizio file, posizione corrente, fine file).
• Valore di ritorno: int. ritorna 0 in caso di successo, altrimenti un valore non-nullo.

Sposta la posizione attuale nello stream: la seguente operazione di lettura o scrittura avverrà alla posizione indicata. In caso di corretta esecuzione, il flag di end of file viene resettato e vengono cancellati tutti i caratteri inseriti nel buffer di lettura tramite la funzione ungetc().

Esempio

Questo codice apre un file chiamato text.txt in sola lettura, prova a forzare il puntatore a FILE all'inizio del file e stampa il contenuto della prima riga del file sullo schermo.

 #include <stdio.h>
 
 int main(int argc, char **argv) {
   FILE *file_pointer;
   file_pointer = fopen("text.txt","r");
   if(fseek(file_pointer, 0, SEEK_SET)) {
     puts("An error occurred");
   }
   else {
     char buffer[100];
     fgets(buffer, 100, file_pointer);
     puts("The first line of the file is:");
     puts(buffer);
   }
   fclose(file_pointer);
   return 0;
 }

fsetpos()

Dichiarazione:

int fsetpos(FILE* stream, const fpos_t* pos);

• Parametri in ingresso:
  • FILE* stream: puntatore allo stream.
  • const fpos_t* pos: posizione (valore impostato da fgetpos().
• Valore di ritorno: int. ritorna 0 in caso di successo, altrimenti un valore non-nullo.

Sposta la posizione attuale nello stream ad una posizione precedentemente memorizzata attraverso la funzione fgetpos(). In caso di corretta esecuzione, il flag di end of file viene resettato e vengono cancellati tutti i caratteri inseriti nel buffer di lettura tramite la funzione ungetc(). In caso di errore, la variabile errno viene impostata a un codice identificativo dell'errore.

ftell()

Dichiarazione:

long int ftell(FILE* stream);

• Parametri in ingresso:
  • FILE* stream: puntatore allo stream.
• Valore di ritorno: long int. ritorna la posizione corrente nello stream, oppure -1L in caso di errore.

Riporta la posizione corrente del puntatore di lettura/scrittura del file stream. In caso di errore, la variabile errno viene impostata a un codice identificativo dell'errore.

fwrite()

Dichiarazione:

size_t fwrite(const void * data, size_t size, size_t count, FILE* stream);

• Parametri in ingresso:
  • const void * data: puntatore ad un array di dati.
  • size_t size: dimensione di un oggetto da scrivere (sizeof(*data)).
  • size_t count: numero di elementi da scrivere.
  • FILE* stream: puntatore allo stream.
• Valore di ritorno: size_t. ritorna il parametro count in caso di successo, un valore diverso indica un errore..

Scrive un numero count di elementi di dimensione size dall'array data nello stream stream.

gets()

Dichiarazione:

char* gets(char* s);

• Valore di ritorno: char*. Restituisce un puntatore alla stringa digitata sulla console.

Legge una riga dallo standard input e la memorizza in un buffer definito dal chiamante.

gets non effettua alcun bounds checking sull'input, quindi è una sorgente potenziale di buffer overflow nei programmi che la usano. Molte man pages della gets contengono il warning "Never use gets" [1] proprio a causa di questo difetto di design.

Anche se l'uso di gets non è ufficialmente deprecato da alcuno standard del C, il suo uso è scoraggiato; è mantenuta negli standard C89 e C99 per retrocompatibilità. Alcuni strumenti di sviluppo emettono warning quando viene linkato del codice che fa uso della funzione gets. La funzione fgets(..., stdin) è un sostituto di gets suggerito frequentemente.

Un uso sicuro di gets richiede che il programmatore si accerti che i buffer overflow non possano esser un problema. Il C standard non fornisce alcuno strumento per assicurare ciò; tuttavia, esiste un certo numero di modi relativamente complicati per assicurarlo, con diversi gradi di portabilità.

Possibile implementazione

 char *gets(char *s)/*<!-- Please don't change me without commenting on the Talk page. -->*/
 {
     int i, k = [[getchar]]();
     /* Ritorna NULL se l'input non esiste */
     if (k == EOF) return NULL;
     /* Legge e memorizza i caratteri fino alla fine del file */
     for (i = 0; k != EOF && k != '\n'; i++) {
         s[i] = k;
         k = getchar();
         /* If a read error occurs, the resulting buffer is not usable. */
         if (k == EOF && !feof(stdin)) return NULL;
     }
     /* Null-terminate and return the buffer on success.
        The newline is not stored in the buffer. */
     s[i] = '\0';
     return s;
 }

remove()

Dichiarazione:

int remove(const char* filename);

• Parametri in ingresso:
  • const char* filename: nome del file.
• Valore di ritorno: int. ritorna 0 in caso di successo, altrimenti un valore non-nullo. Per l'elenco completo degli errori, vedi [2]..

Cancella il file di nome filename.

rename()

Dichiarazione:

int rename(const char* oldfilename, const char* newfilename);

• Parametri in ingresso:
  • const char* oldfilename: nome originale.
  • const char* newfilename: nuovo nome.
• Valore di ritorno: int. ritorna 0 in caso di successo, altrimenti un valore non-nullo.

Modifica il nome del file oldfilename in newfilename. newfilename può trovarsi in un'altra directory rispetto al file originale, ma sullo stesso file system. In caso di errore, la variabile errno viene impostata a un codice identificativo dell'errore. Per un elenco completo degli errori che si possono verificare, vedi [3].

rewind()

Dichiarazione:

void rewind(FILE* stream);

• Parametri in ingresso:
  • FILE* stream: puntatore allo stream.
• Valore di ritorno: void.

Reimposta la posizione del puntatore di lettura/scrittura del file stream all'inizio del file. Gli indicatori di errore e di fine file sono reimpostati a zero.

setbuf()

Dichiarazione:

void setbuf(FILE* stream, char* buf);

• Parametri in ingresso:
  • FILE* stream: puntatore allo stream.
  • char* buf: array da usare come buffer (almeno di dimensione BUFSIZ), oppure NULL.
• Valore di ritorno: void.

Imposta il buffer per lo stream stream. Se il parametro buf è uguale a NULL, la funzione è equivalente a setvbuf(stream, NULL, _IONBF, 0), altrimenti è equivalente a setvbuf(stream, buf, _IOFBF, BUFSIZ).

Nota: la funzione setvbuf() è da preferire.

setvbuf()

Dichiarazione:

int setbuf(FILE* stream, char* buf, int mode, size_t size);

• Parametri in ingresso:
  • FILE* stream: puntatore allo stream.
  • char* buf: array da usare come buffer (almeno di dimensione size), oppure NULL.
  • int mode: modalità di bufferizzazione. Può assumere come valori _IOFBF, _IOLBF oppure _IONBF.
  • size_t size: dimensione del buffer.
• Valore di ritorno: int. ritorna 0 in caso di successo, altrimenti un valore non-nullo.

Imposta il buffer per lo stream stream. Il parametro mode controlla il tipo di bufferizzazione:

• _IOFBF: bufferizzazione completa;
• _IOLBF: bufferizzazione di una singola riga;
• _IONBF: nessuna bufferizzazione.

Se il parametro buf è uguale a NULL e il parametro mode è diverso da _IONBF, il buffer viene allocato internamente tramite la funzione malloc(), e liberato alla chiusura dello stream.

Nota: finché l'array buf rimane associato ad uno stream, è bene non cercare di accedere ai suoi elementi direttamente, perché gli effetti non sono definiti.

tmpfile()

Dichiarazione:

FILE* tmpfile();

• Valore di ritorno: FILE*. Restituisce un puntatore a uno stream valido in caso di successo, o NULL in caso di errore.

Crea un file temporaneo e lo apre in modalità "wb+" (vedi fopen()). Alla chiusura dello stream o al termine del programma, il file viene cancellato.

tmpnam()

Dichiarazione:

char* tmpnam(char* result);

• Parametri in ingresso:
  • char* result: un array di almeno L_tmpnam caratteri, oppure NULL.
• Valore di ritorno: char*. Restituisce un puntatore ad una scringa contenente il nome del file.

Genera un nome di file valido che può essere usato come nome di un file temporaneo. Nel caso in cui il parametro result sia NULL, il nome viene memorizzato in un array interno e viene restituito un puntatore a tale array, il che rende la funzione non-rientrante (cioè modifica il suo stato se viene chiamata successivamente). Se invece il parametro result è un array valido, il nome del file viene memorizzato in esso.

Nota: l'uso della funzione tmpfile è generalmente più sicuro.