C Standard Library

C Standard Library - stdio.h
Gio 06 Mar 2008

#define _IOFBF <espressione intera costante>
#define _IOLBF <espressione intera costante>
#define _IONBF <espressione intera costante>
#define BUFSIZ <espressione intera costante >= 256>
#define EOF <espressione intera costante < 0>
#define FILENAME_MAX <espressione intera costante > 0>
#define FOPEN_MAX <espressione intera costante >= 8>
#define L_tmpnam <espressione intera costante > 0>
#define NULL <uno fra 0, 0L, (void *)0>
#define SEEK_CUR <espressione intera costante>
#define SEEK_END <espressione intera costante>
#define SEEK_SET <espressione intera costante>
#define TMP_MAX <espressione intera costante>

extern FILE *stdin;
extern FILE *stdout;
extern FILE *stderr;

#define stdin stdin
#define stdout stdout
#define stderr stderr

void clearerr(FILE *f);
int fclose(FILE *f);
int feof(FILE *f);
int ferror(FILE *f);
int fflush(FILE *f);
int fgetc(FILE *f);
int fgetpos(FILE *f, fpos_t *pos);
char *fgets(char *s, int n, FILE *f);
FILE *fopen(const char *filename, const char *mode);
int fprintf(FILE *f, const char *format, ...);
int fputc(int c, FILE *f);
int fputs(const char *s, FILE *f);
size_t fread(void *ptr, size_t dim, size_t n, FILE *f);
FILE *freopen(const char *filename, const char *mode, FILE *f);
int fscanf(FILE *f, const char *format, ...);
int fseek(FILE *f, long offset, int mode);
int fsetpos(FILE *f, const fpos_t *pos);
long ftell(FILE *f);
size_t fwrite(const void *ptr, size_t dim, size_t n, FILE *f);
int getc(FILE *f);
int getchar(void);
char *gets(char *s);
void perror(const char *s);
int printf(const char *format, ...);
int putc(int c, FILE *f);
int putchar(int c);
int puts(const char *s);
int remove(const char *filename);
int rename(const char *old, const char *new);
void rewind(FILE *f);
int scanf(const char *format, ...);
void setbuf(FILE *f, char *buf);
int setvbuf(FILE *f, char *buf, int mode, size_t size);
typedef ui-type size_t;
int sprintf(char *s, const char *format, ...);
int sscanf(const char *s, const char *format, ...);
FILE *tmpfile(void)
char *tmpnam(char *s);
int ungetc(int c, FILE *f);
int vfprintf(FILE *f, const char *format, va_list ap);
int vprintf(const char *format, va_list ap);
int vsprintf(char *s, const char *format, va_list ap);

BUFSIZ

Dimensione del buffer utilizzato dalla funzione setbuf. Deve avere dimensione minima pari a 256.

EOF

Valore utilizzato per indicare la fine di un file o per riportare un errore.

FILE

Il tipo FILE descrive uno stream, contiene informazioni necessari per il controllo dello stream. È una struttura contenente informazioni su un file.

typedef struct {
...
} FILE;

La definizione della struttura varia da sistema operativo a sistema operativo. In genere sono presenti campi contenenti informazioni sul nome del file, la dimensione del buffer, il descrittore del file, eccetera.
Un esempio di struttura è il seguente

typedef struct {
int cnt;
unsigned char *b_ptr;
unsigned char *base;
int bufsize;
short flag;
char fd;
} FILE;

FILENAME_MAX

Lunghezza massima richiesta per l'array di caratteri che conterrà il filename.

FOPEN_MAX

Numero massimo di file che è possibile aprire contemporaneamente.

fpos_t

È usato dalle funzioni fgetpos e fsetpos per rappresentare la posizione corrente all'interno di un file. Struttura contenente le informazioni relative alla posizione all'interno di un file. La definizione della struttura varia da sistema operativo a sistema operativo. Un esempio di struttura è il seguente

typedef struct {
unsigned int lopart;
int hipart;
} fpos_t;

L_tmpnam

Dimensione massima del nome di file temporaneo generato dalla funzione tmpnam.

NULL

Costante puntatore NULL.

SEEK_CUR

Usata come argomento per la funzione fseek indica che la ricerca nel file deve partire dalla posizione corrente.

SEEK_END

Usata come argomento per la funzione fseek indica che la ricerca nel file deve partire dalla fine del file.

SEEK_SET

Usata come argomento per la funzione fseek indica che la ricerca nel file deve partire dall'inizio del file.

TMP_MAX

Numero massimo di file temporanei che possono essere creati dalla funzione tmpnam.

_IOFBF

Usata come argomento per la funzione setvbuf indica che lo stream deve essere completamente bufferizzato.

_IOLBF

Usata come argomento per la funzione setvbuf indica che lo stream deve essere bufferizzato a linee.

_IONBF

Usata come argomento per la funzione setvbuf indica che lo stream non deve essere bufferizzato.

stdin

Puntatore allo stream di standard input, viene automaticamente aperto all'inizio del programma.

stdout

Puntatore allo stream di standard output, viene automaticamente aperto all'inizio del programma.

stderr

Puntatore allo stream di standard error, viene automaticamente aperto all'inizio del programma.

size_t

Tipo restituito dall'operatore sizeof.

void	clearerr(FILE* `f`);

Rimuove l'indicatore di errore associato al file f.

int	fclose(FILE* `f`);

Chiude il file associato a f. Tutti i buffer associati vengono svuotati: i dati bufferizzati non ancora scritti vengono scritti, i dati bufferizzati letti vengono persi. Restituisce EOF in caso di errore, 0 in caso di successo.
La terminazione del programma causa una chiamata a fclose per ogni file aperto.

int	feof(FILE* `f`);

Restituisce zero se non è stata raggiunta la fine del file, zero in caso contrario.

int	ferror(FILE* `f`);

Esamina l'indicatore di errore associato al file, e restituisce zero se si è verificato un errore sul file, e un valore diverso da zero se non si è verificato nessun errore.

int	fflush(FILE* `f`);

Se f è aperto in scrittura e l'ultima operazione sul file è stata una scrittura tutti i dati non scritti presenti nel buffer vengono scritti sul file. Se f è aperto in lettura e l'ultima operazione sul file è stata una lettura il comportamento della fflush è indefinito. Se f = NULL la fflush viene applicata a tutti i file aperti.
Il file rimane aperto anche dopo l'esecuzione della fflush. Quando un file viene chiuso, o tramite una chiamata alla fclose o perché il programma termina, il buffer relativo ai vari file viene svuotato.
Restituisce zero in caso di successo, EOF in caso di fallimento.

int	fgetc(FILE* `f`);

Legge un carattere dal file indicato e lo restituisce convertendolo in un intero. Il carattere viene letto come unsigned char e viene converito in un int prima di essere restituito. Dopo la lettura del carattere l'indicatore della posizione nel file viene fatto avanzare di una posizione. Se si è raggiunta la fine del file restituisce EOF. Se si verifica un errore restituisce EOF.

int	fgetpos(FILE* `f`, fpos_t* `ptr`);

Restituisce il valore dell'indicatore di posizione del file memorizzandolo nell'area indirizzata da ptr. Restituisce zero se non si sono verificati errori, in caso contrario restituisce un valore diverso da zero.

char*

fgets(char* s, int n, FILE* f);

Legge un carattere dal file indicato e lo restituisce convertendolo in un intero. Il carattere viene letto come unsigned char e viene convertito in un int prima di essere restituito. Dopo la lettura del carattere l'indicatore della posizione nel file viene fatto avanzare di una posizione. Se si è raggiunta la fine del file restituisce EOF. Se si verifica un errore restituisce EOF.

FILE*

fopen(const char* filename, const char* mode);

Apre il file il cui nome è contenuto in filename e restituisce un puntatore ad un oggetto di tipo FILE in caso di successo o NULL, in caso di fallimento. filename non può essere più lungo di FILENAME_MAX caratteri.
È possibile specificare il modo con cui aprire il file tramite il parametro mode, che può assumere i seguenti valori

mode	descrizione
r	file aperto in lettura
w	file aperto in scrittura
a	file append (i dati possono essere aggiunti solo alla fine del file)
r+	file aperto per l'update (lettura e scrittura)
w+	file aperto per l'update (lettura e scrittura)
a+	file append (lettura, scrittura solo alla fine del file)

Aggiungendo la lettera b alla fine del primo carattere ("rb", "rb+", ecc.) si indica che si opererà su un file binario.
Per poter aprire in lettura un file (presenza di "r" nel parametro mode) il file deve esistere e contenere dati.
Un file aperto in scrittura (presenza di "w" nel parametro mode) se già esiste viene troncato e riscritto da zero, se non esiste viene creato.
Un file aperto per l'update (presenza di "+" nel parametro mode) permette di leggere e scrivere dal/sul file. Nelle combinazioni "r+" e "w+" è possibile leggere e scrivere in un punto qualsiasi del file. Nella combinazione "a+" sarà possibile leggere in qualsiasi punto del file, ma sarà possibile scrivere solo alla fine del file.
Le stringhe per il parametro mode possono essere: "a", "ab", "a+", "ab+", "a+b", "r", "rb", "r+", "rb+", "r+b", "w", "wb", "w+", "wb+", "w+b".
Per poter passare dalla lettura alla scrittura sul file è necessario scaricare il buffer di input tramite la fflush oppure riposizionare l'indicatore di posizione tramite la fseek, la fsetpos o la rewind.
Tramite la fopen è possibile aprire un massimo di FOPEN_MAX file contemporanemante.

int	fprintf(FILE* `f`, const char* `format`, ...);

Converte, secondo la stringa di formato, e scrive su file la stringa indicata.
Per le regole sulla stringa di formato vedere la printf.

int	fputc(int `c`, FILE* `f`);

Scrive un carattere su un file. Riceve un intero, lo converte in un unsigned char e lo scrive sul file. L'indicatore della posizione del file viene fatto avanzare di una posizione. Se la scrittura ha avuto successo restituisce il carattere scritto, altrimenti restituisce EOF.

char*

fputs(const char* s, FILE* f);

Scrive la stringa puntata da s nel file. A differenza della puts non scrive il carattere newline alla fine della stringa. Se la scrittura ha avuto successo restituisce un numero non negativo, altrimenti restituisce EOF.

size_t

fread(void* ptr, size_t dim, size_t n, FILE* f);

Legge dal file indicato n elementi ciascuno di dimensione pari a dim byte e li pone nell'area di memoria puntata da ptr. Se l'operazione di lettura ha avuto successo restituisce il numero di elementi letti, se non ha avuto successo, nel caso vi sia stato un errore o si sia raggiunta la fine del file, viene restituito un numero di elementi inferiore a n. Per sapere quale delle due possibilità (errore o fine del file) si è verificata si devono usare le due funzioni feof e ferror.

FILE*

freopen(const char* filename, const char* mode, FILE* f);

Chiude il file associato a f, quindi apre il file di nome filename nel modo specificato da mode e gli associa f. Restituisce un puntatore al file in caso di successo o NULL in caso di fallimento.

int	fscanf(FILE* `f`, const char* `format`, ...);

Legge una sequenza di caratteri dal file f e li pone nelle variabili, i cui puntatori sono passati come argomenti della funzione, convertendoli in base alla stringa di formattazione format.

int	fseek(FILE* `f`, long `offset`, int `origin`);

Assegna un valore all'indicatore della posizione del file f, in questo modo viene spostato il punto del file su cui sarà effettuata la prossima operazione di input/output. L'indicatore di posizione sarà spostato a partire dalla posizione origine di un numero di byte pari a spiazzamento. origine può assumere i valori

origine	Descrizione
SEEK_CUR	La posizione corrente
SEEK_END	La fine del file
SEEK_SET	L'inizio del file

int	fsetpos(FILE* `f`, const fpos_t* `ptr`);

Modifica l'indicatore di posizione del file che diventa pari a ptr.

long	ftell(FILE* `f`);

Restituisce il valore dell'indicatore di posizione del file f. In caso di errore restituisce -1.

size_t

fwrite(const void* ptr, size_t dim, size_t n, FILE* f);

Scrive nel file fino a n elementi, ciascuno di dimensione pari a dim byte, contenuti nell'area puntata da ptr. L'indicatore della posizione del file viene fatto avanzare di una quantità pari al numero di byte scritti, ovvero (dim * n) byte. Se l'operazione di scrittura ha avuto successo restituisce il numero di elementi scritti, altrimenti restituisce un numero inferiore.

int	getc(FILE* `f`);

Legge un carattere dallo stream indicato e restituisce il carattere letto convertendolo in un intero. Se si è raggiunta la fine del file restituisce EOF, altrimenti restituisce il carattere letto convertito in un intero. Se si è verificato un errore restituisce EOF. Dopo la lettura del carattere l'indicatore della posizione nel file viene fatto avanzare di una posizione.

int	getchar(void);

Legge un carattere da stdin. Equivale a getc(stdin). Se si raggiunge la fine del file restituisce EOF, se si verifica un errore restituisce EOF.

char*

gets(char* s);

Legge una riga dallo standard input e la memorizza nell'area di memoria puntata da s. Legge caratteri dallo standard input fino a quando non incontra un carattere di newline o fino a quando non incontra la fine del file. Restituisce la sequenza di caratteri letta, priva del carattere newline o di EOF, aggiungendo come ultimo carattere il carattere nullo ('\0'), se dopo aver letto alcuni caratteri si arriva alla fine del file restituisce NULL e quei caratteri letti sono restituiti in s. Se si verifica un errore restituisce NULL.

void	perror(const char* `s`);

Analizza lo stato di errno e scrive il messaggio di errore ad esso associato sullo standard error.

int	printf(const char* `format`, ...);

Stampa un testo formattandolo come specificato nella stringa di formato. Costruisce una stringa di testo in base alla stringa di formato e la scrive su stdout. La stringa di formato è costituita da del testo e da una o più specifiche di conversione.
Una specifica di conversione ha la forma seguente: %[flags][width][.precision][length]specifier

Flag
Flag	Descrizione
-	Giustifica a sinistra il campo corrispondente. Per default è attiva la giustificazione a destra.
+	Forza la scrittura del segno
(spazio)	Se è un numero senza segno viene stampato un carattere spazio davanti al numero
#	Utilizzato con le lettere e, E, f, F forza a scrivere il numero con il punto decimale anche in assenza di cifre dopo il punto. Utilizzato con le lettere g o G in assenza di cifre dopo il punto decimale, viene scritto il punto decimale e lo zero successivo. Utilizzato con o, x o X forza la stampa di "0", "0x" o "0X", per valori diversi da zero, prima del numero. Per default in assenza di cifre dopo il punto decimale, il punto decimale non viene scritto.
0	Fa precedere il numero con un certo numero di zeri, numero specificato subito dopo ([width]).

Width
Width	Descrizione
(num)	Si definisce il numero di caratteri, pari a num, di cui deve essere costituito il numero da scrivere. Se il numero da scrivere è costituito da un numero di caratteri inferiore a num vengono inseriti prima del numero un numero di zeri sufficiente a raggiungere num caratteri.
*	Il numero di caratteri di cui dovrà essere costituito il campo è specificato dall'argomento indicato.

precision

Precision

Descrizione

.num

La precisione è specificata da un punto decimale seguito da un numero, se manca questo numero si assume una precisione pari a 0.
La precisione indica il numero di caratteri che devono essere scritti per quel determinato parametro.

Specificatore	Descrizione
d	Scrivi almeno num cifre
e, E, f	Scrivi num cifre dopo il punto decimale
g, G	Scrivi al più num cifre significative
i, o, u, x, X	Scrivi almeno num cifre
s	Scrivi al più num caratteri

Il numero di caratteri è specificato dall'argomento.

Length
Length	Descrizione
h	Indica che l'argomento corrispondente è uno short int o un unsigned short int se usato prima di uno di questi specificatori di conversione: i, d, o, u, x, X.
l	Indica che l'argomento corrispondente è uno long int o un unsigned long int se usato prima di uno di questi specificatori di conversione: i, d, o, u, x, X.
L	Indica che l'argomento corrispondente è uno long double se usato prima di uno di questi specificatori di conversione: e, E, f, g, G.

L'applicazione dei modificatori h, l, L ad uno specificatore diverso da quello indicati porta ad un risultato indefinito.

Specificatori
Specificatore	Descrizione
c	Carattere
d o i	Intero con segno
e	Numero in virgola mobile in notazione scientifica
E	Numero in virgola mobile in notazione scientifica
f	Numero in virgola mobile in notazione decimale fissa
g	Numero in virgola mobile
G	Numero in virgola mobile
o	Intero espresso in ottale senza segno
s	Stringa di caratteri
u	Intero senza segno
x	Intero espresso in esadecimale senza segno
X	Intero espresso in esadecimale senza segno (lettere maiuscole)
p	Puntatore
n	Specifica che accetta un puntatore ad intero all'interno del quale scrive il numero di caratteri che la printf ha generato fino alla posizione corrente di formato.
%	Inserendo due % di seguito verrà stampato un %.

Esempio
Il programma seguente

#include <stdio.h>
int main()
{
printf ("Carattere: %c, %c\n", 'i', 105);
printf ("Numeri Decimali: %d, %ld\n", 2329, 650000);
printf ("Sistemi di Numerazione diversi: %d , %x, %X, %o \n",
100, 62435, 62435, 100);
printf ("Numeri in virgola mobile: %f, %e, %E\n", 3.1416, 3.1416, 3.1416);
printf ("Numeri in virgola mobile: %g, %G\n", 3.1416, 3.1416);
printf ("Stringa: \"%s\" \n", "Esempio Stringa");
printf ("Scrittura Segno: %+d, %+d \n", 10, -10);
printf ("(spazio):% d (spazio):%d\n", 10, 10);
printf ("#: %#e, %#x, %#o\n", 3., 100, 100);
printf ("Numero preceduto da spazi: %7d\n", 2048);
printf ("Numero preceduto da zero: %07d\n", 2048);
printf ("Ampiezza Minima Campo: %4d, %*d\n", 5, 10);
printf ("Precisione: %.2f, %.0f, %.*f\n", 3.1416, 3.1416, 3, 3.1416);
printf ("Precisione: %.2d, %.2e, %.2s\n", 3450, 3.1416, "Stringa");
printf ("Varie: %4.2f \n", 3.1416);
}

produce i seguenti risultati

Carattere: i, i
Numeri Decimali: 2329, 650000
Sistemi di Numerazione diversi: 100 , f3e3, F3E3, 144
Numeri in virgola mobile: 3.141600, 3.141600e+000, 3.141600E+000
Numeri in virgola mobile: 3.1416, 3.1416
Stringa: "Esempio Stringa"
Scrittura Segno: +10, -10
(spazio): 10 (spazio):10
#: 3.000000e+000, 0x64, 0144
Numero preceduto da spazi: 2048
Numero preceduto da zero: 0002048
Ampiezza Minima Campo: 5, 100
Precisione: 3.14, 3, 3.142
Precisione: 3450, 3.14e+000, St
Varie: 3.14

int	putc(int `c`, FILE* `f`);

Scrive un carattere in uno stream. Scrive il carattere contenuto in c nello stream puntato da f. Restituirà il carattere scritto se l'operazione di scrittura si è svolta correttamente, altrimenti restituirà EOF.

int	putchar(int `c`);

Scrive un carattere su stdout, è equivalente a putc(c, stdout). Restituisce il carattere scritto se l'operazione di scrittura è stata svolta correttamente, in caso contrario restituirà EOF.

int	puts(const char* `s`);

Scrive una stringa su stdout sostituendo il carattere nullo '\0' presente alla fine della stringa, e che contraddistingue la fine della stringa, con il carattere newline '\n'. puts inizia dal primo carattere della stringa e scrive i caratteri su stdout fino a quando non incontra il carattere nullo '\0'. Il carattere nullo non è scritto su stdout, al suo posto sarà scritto il carattere newline '\n'.

int	remove(const char* `filename`);

Cancella il file con nome filename, restituisce zero in caso di successo o un valore diverso da zero in caso di fallimento.

int	rename(const char* `oldname`, const char* `newname`);

Rinomina il file il cui nome è in oldname con il nome che è in newname.

void	rewind(FILE* `f`);

Azzera l'indicatore della posizione associato al file. È equivalente a fseek(f, 0L, SEEK_SET);

int	scanf(const char* `format`, ...);

Legge una sequenza di caratteri da stdin e li pone nelle variabili, i cui puntatori sono passati come argomenti della funzione, convertendoli in base alla stringa di formattazione format. Per le specifiche di conversione vedere printf.

void	setbuf(FILE* `f`, char* `buf`);

Al momento dell'apertura di un file, con la funzione fopen o con la funzione freopen, viene assegnato un buffer, di dimensione BUFSIZ byte, al file. Tramite la funzione setbuf è possibile sostituire il buffer di default associato al file f con un nuovo buffer puntato da buf che si assume di dimensione BUFSIZ.
Il buffer dovrebbe essere cambiato una volta aperto il file ma prima di aver compiuto una qualsiasi operazione di lettura o di scrittura.

int	setvbuf(FILE* `f`, char* `buf`, int `mode`, size_t `size`);

Al momento dell'apertura di un file, con la funzione fopen o con la funzione freopen, viene assegnato un buffer, di dimensione BUFSIZ byte, al file. Tramite la funzione setvbuf è possibile sostituire il buffer di default associato al file f con un nuovo buffer puntato da buf.
È possibile impostare la dimensione del nuovo buffer tramite size, e la modalità di bufferizzazione tramite mode, che può assumere i seguenti valori

mode	descrizione
_IOFBF	Totalmente bufferizzato
_IOLBF	Bufferizzato a Linee
_IONBF	Non bufferizzato

int	sprintf(char* `s`, const char* `format`, ...);

Equivalente alla fprintf tranne per il fatto che il testo viene scritto in una stringa e non in un file. Il testo scritto è terminato dal carattere NULL. Se l'operazione ha avuto successo restituisce il numero di caratteri scritti (non considerando il carattere NULL), se non ha successo restituisce un valore negativo.

int	sscanf(char* `s`, const char* `format`, ...);

Legge una sequenza di caratteri dalla stringa s e li pone nelle variabili, i cui puntatori sono passati come argomenti della funzione, convertendoli in base alla stringa di formattazione format. Per le specifiche di conversione vedere printf.

FILE*

tmpfile();

Crea un file temporaneo (con mode "wb+") che sarà rimosso quando il programma terminerà. In caso di successo restituisce un puntatore al file, in caso di fallimento restituisce NULL.

char*

tmpnam(char s[L_tmpnam]);

Crea un nome univoco per un file temporaneo, il nome avrà dimensione massima di L_tmpnam caratteri. Si potranno produrre fino a TMP_MAX nomi.
Una volta creato il nome si dovrà creare il file. File che dovrà poi essere chiuso alla chiusura del programma.

int	ungetc(int `c`, FILE* `f`);

Converte c in un unsigned char e lo restituisce al file puntato da f, in modo che potrà essere prelevato dalla prossima operazione di input dal file.
Restituisce c se l'operazione ha successo o EOF se non ha successo. Nel caso in cui c = EOF l'operazione fallisce.

int	vfprintf(FILE* `f`, const char* `format`, va_list `arg`);

Costruisce una stringa formattata in base alla stringa di formato e la scrive su un file. A differenza della fprintf può ricevere una lista variabile di argomenti diversi.

int	vprintf(const char* `format`, va_list `arg`);

Costruisce una stringa formattata in base alla stringa di formato e la scrive sullo standard output. A differenza della printf può ricevere una lista variabile di argomenti diversi.

int	vsprintf(char* `s`, const char* `format`, va_list `arg`);

Costruisce una stringa formattata in base alla stringa di formato e la scrive su una stringa. A differenza della sprintf può ricevere una lista variabile di argomenti diversi.