Sintassi della specifica del formato: printf e wprintf funzioni

Le diverse funzioni printf e wprintf accettano una stringa di formato e argomenti facoltativi e producono una sequenza di caratteri formattati per l'output. La stringa di formato contiene zero o più direttive, che sono caratteri letterali per l'output o specifiche di conversione codificate che descrivono come formattare un argomento nell'output. Questo articolo descrive la sintassi usata per codificare le specifiche di conversione nella stringa di formato. Per l'elenco di queste funzioni, vedere I/O di flusso.

Una specifica di conversione è costituita da campi obbligatori e facoltativi nel seguente formato:

%[flag][larghezza][.precisione][dimensione]tipo

Ogni campo della specifica di conversione è un carattere o un numero che indica un particolare identificatore di conversione o opzione di formato. Il campo obbligatorio tipo specifica il tipo di conversione da applicare a un argomento. I flag facoltativi, la larghezza e i campi di precisione controllano altri aspetti del formato, ad esempio spazi iniziali o zeri, giustificazione e precisione visualizzata. Il campo dimensione specifica la dimensione dell'argomento usato e convertito.

Una specifica di conversione semplice contiene solo il segno di percentuale e un carattere tipo. Ad esempio, %s specifica una conversione di stringhe. Per stampare un carattere di segno di percentuale, usare %%. Se un segno di percentuale è seguito da un carattere che non ha alcun significato come campo di formato, viene chiamato il gestore di parametro non valido. Per altre informazioni, vedere Convalida dei parametri.

Importante

Per motivi di sicurezza e stabilità, assicurarsi che le stringhe di specifica di conversione del formato non siano definite dall'utente finale. Ad esempio, si consideri un programma che richiede all'utente di inserire un nome e archivia l'input in una variabile di stringa denominata user_name. Per stampare user_name, non eseguire mai questa operazione:

printf( user_name ); /* Danger! If user_name contains "%s", program will crash */

Al contrario, eseguire questa operazione:

printf( "%s", user_name );

Nota

In Visual Studio 2015 Le printf funzioni e scanf la famiglia di funzioni sono state dichiarate come inline e spostate nelle <stdio.h> intestazioni e <conio.h> . Se si esegue la migrazione di codice meno recente, è possibile che vengano visualizzati LNK2019 in relazione a queste funzioni. Per altre informazioni, vedere Cronologia delle modifiche di Visual C++ 2003 - 2015.

Identificatore di conversione tipo

Il carattere identificatore di conversione tipo specifica se l'argomento corrispondente deve essere interpretato come un carattere, una stringa, un puntatore, un numero intero o un numero a virgola mobile. Il carattere tipo è l'unico campo di specifica conversione obbligatorio e viene visualizzato dopo tutti i campi facoltativi.

Gli argomenti che seguono la stringa di formato vengono interpretati a seconda del carattere tipo corrispondente e del prefisso dimensione facoltativo. Le conversioni per i tipi di char caratteri e wchar_t vengono specificate usando c o Ce le stringhe di caratteri a byte singolo e multibyte o wide vengono specificate tramite s o S, a seconda della funzione di formattazione in uso. Gli argomenti carattere e stringa specificati tramite e c s vengono interpretati come char e char* dalle printf funzioni della famiglia o come wchar_t e wchar_t* in wprintf base alle funzioni della famiglia. Gli argomenti carattere e stringa specificati tramite e C S vengono interpretati come wchar_t e wchar_t* dalle printf funzioni della famiglia o come char e char* in wprintf base alle funzioni della famiglia. Questo comportamento è specifico di Microsoft. Per motivi cronologici, le wprintf funzioni usano c e s per fare riferimento ai wchar_t caratteri e S C specificano caratteri stretti.

I tipi integer, ad shortesempio , intlong, long long, e le relative unsigned varianti, vengono specificati usando d, oxiue .X I tipi a virgola mobile, ad esempio , e , vengono specificati usando a, efgFAEe .Glong doubledoublefloat Per impostazione predefinita, a meno che non vengano modificati da un prefisso di dimensione , gli argomenti integer vengono coerciti per int il tipo e gli argomenti a virgola mobile vengono coerciti su double. Nei sistemi a 64 bit, un int è un valore a 32 bit. Pertanto, i numeri interi a 64 bit verranno troncati quando vengono formattati per l'output, a meno che non venga usato un prefisso di dimensione di ll o I64 . I tipi di puntatore specificati da p usano le dimensioni del puntatore predefinite per la piattaforma.

Nota

Specifico di Microsoft:
Il Z carattere di tipo e il comportamento dei ccaratteri di tipo , Cs, e S quando vengono usati con le printf funzioni ewprintf, sono estensioni Microsoft. Lo standard ISO C usa c e s costantemente per caratteri e stringhe strette e C per S caratteri e stringhe wide, in tutte le funzioni di formattazione.

Caratteri del campo tipo

Carattere tipo	Argomento	Formato di output
c	Carattere	Una volta usato con funzioni printf, specifica un carattere a byte singolo; quando usato con funzioni wprintf, specifica un carattere wide.
C	Carattere	Una volta usato con funzioni printf, specifica un carattere wide; quando usato con funzioni wprintf, specifica un carattere a byte singolo.
d	Intero	Intero decimale con segno.
i	Intero	Intero decimale con segno.
o	Intero	Intero ottale senza segno.
u	Intero	Intero decimale senza segno.
x	Intero	Intero esadecimale senza segno; usa "abcdef".
X	Intero	Intero esadecimale senza segno; usa "ABCDEF".
e	A virgola mobile	Il valore con segno con il formato [-]d.dddde[-+|]dd[d], dove d è una cifra decimale, dddd è una o più cifre decimali a seconda della precisione specificata, o sei per impostazione predefinita, e dd[d] è di due o tre cifre decimali a seconda del formato di output e delle dimensioni dell'esponente.
E	A virgola mobile	Identico al formato, ad eccezione del e fatto che E anziché e introdurre l'esponente.
f	A virgola mobile	Valore con segno con il formato [-]dddd.dddd, dove dddd è una o più cifre decimali. Il numero di cifre prima del separatore decimale dipende dalla grandezza del numero, mentre il numero di cifre dopo il separatore decimale dipende dalla precisione richiesta o corrisponde a sei per impostazione predefinita.
F	A virgola mobile	Identico al formato, ad eccezione del f fatto che l'output infinito e NaN è in maiuscolo.
g	A virgola mobile	I valori con segno vengono visualizzati in f formato o e , a meno che sia più compatto per il valore e la precisione specificati. Il e formato viene utilizzato solo quando l'esponente del valore è minore di -4 o maggiore o uguale all'argomento precisione. Gli zeri finali vengono troncati e il separatore decimale viene visualizzato solo se uno o più cifre lo seguono.
G	A virgola mobile	Identico al formato, ad eccezione del g fatto che E, anziché e, introduce l'esponente (se appropriato).
a	A virgola mobile	Valore a virgola mobile esadecimale con precisione doppia con segno [-]0xh.hhhhp[+-|]dd, dove h.hhhhh sono le cifre esadecimali (usando lettere minuscole) della mantissa e dd sono una o più cifre per l'esponente. La precisione indica il numero di cifre dopo il punto.
A	A virgola mobile	Valore a virgola mobile esadecimale con precisione doppia con segno [-]0Xh.hhhhP[+-|]dd, dove h.hhhhh sono le cifre esadecimali (utilizzando lettere maiuscole) della mantissa e dd sono una o più cifre per l'esponente. La precisione indica il numero di cifre dopo il punto.
n	Puntatore a intero	Numero di caratteri che viene scritto correttamente fino al flusso o nel buffer. Questo valore viene archiviato nel valore intero in cui l'indirizzo viene fornito come argomento. Le dimensioni del numero intero al quale si fa riferimento possono essere controllate da un prefisso di indicazione delle dimensioni dell'argomento. L'identificatore n è disattivato per impostazione predefinita. Per informazioni vedere l'importante nota sulla sicurezza.
p	Tipo di puntatore	Visualizzare l'argomento come indirizzo in cifre esadecimali.
s	String	Una volta usato con funzioni printf, specifica una stringa di caratteri a byte singolo o multibyte; una volta usato con le funzioni wprintf, specifica una stringa di carattere wide. I caratteri vengono visualizzati fino al primo carattere Null o fino a quando non viene raggiunto il valore precisione.
S	String	Una volta usato con funzioni printf, specifica una stringa di caratteri wide; una volta usato con le funzioni wprintf, specifica una stringa di caratteri a un byte singolo o multibyte. I caratteri vengono visualizzati fino al primo carattere Null o fino a quando non viene raggiunto il valore precisione.
Z	Struttura ANSI_STRING o UNICODE_STRING	VS 2013 e versioni precedenti Quando l'indirizzo di una ANSI_STRING struttura o UNICODE_STRING viene passato come argomento, visualizzare la stringa contenuta nel buffer a cui punta il Buffer campo della struttura. Usare un prefisso del modificatore di dimensioni di w per specificare un UNICODE_STRING argomento, %wZad esempio . Il campo Length della struttura deve essere impostato sulla lunghezza, espressa in byte, della stringa. Il campo MaximumLength della struttura deve essere impostato sulla lunghezza, espressa in byte, del buffer. Universal C Runtime (UCRT) Esiste un problema noto in UCRT attualmente mantenuto per la compatibilità. Analogamente all'identificatore, l'identificatore senza un prefisso del modificatore di dimensioni fa riferimento a quando UNICODE_STRING si usa una funzione di stampa stretta (ad esempio ) e un ANSI_STRING quando si usa una funzione di stampa wide (ad esempio wprintfprintf).S Z ZAnziché , usare hZ per specificare un oggetto ANSI_STRING. wZ (o lZ) può comunque essere usato per specificare un oggetto UNICODE_STRING. In genere, il Z carattere di tipo viene usato solo nelle funzioni di debug del driver che usano una specifica di conversione, ad esempio dbgPrint e kdPrint.

In Visual Studio 2015 e versioni successive, se l'argomento che corrisponde a un identificatore di conversione a virgola mobile (a, A, feFE, gG) è infinito, indefinito o NaN, l'output formattato è conforme allo standard C99. Questa tabella elenca l'output formattato:

Valore	Output
Infinito	inf
NaN non interattivo	nan
Segnalazione NaN	nan(snan)
NaN indefinito	nan(ind)

Una di queste stringhe può essere preceduta da un segno. Se un carattere identificatore di conversione tipo a virgola mobile è una lettera maiuscola, anche l'output viene formattato in lettere maiuscole. Ad esempio, se l'identificatore di formato è %F anziché %f, un infinity viene formattato come INF anziché come inf. Anche le funzioni scanf possono analizzare queste stringhe, pertanto questi valori possono completare un round trip tra le funzioni printf e scanf.

Prima di Visual Studio 2015, la libreria CRT usava un formato diverso, non standard per l'output di valori infinite, indefinite e NaN:

Valore	Output
+ Infinito	1.#INFcifre casuali
-Infinità	-1.#INFcifre casuali
Non definito (stesso valore di NaN non interattivo)	cifre .#IND casuali cifre
NaN	cifre .#NAN casuali cifre

Una di queste stringhe può essere stata preceduta da un segno e potrebbe essere stata formattata in modo diverso a seconda della larghezza e della precisione del campo, talvolta con effetti insoliti. Ad esempio, printf("%.2f\n", INFINITY) stampa 1.#J perché il #INF verrebbe "arrotondato" a due cifre di precisione.

Nota

Se l'argomento corrispondente a %s o %S o il campo Buffer dell'argomento corrispondente a %Z è un puntatore null, viene visualizzato "(null)".

Nota

In tutti i formati esponenziali, il numero minimo di cifre dell'esponente da visualizzare è due; tre cifre vengono usate solo in caso di necessità. Usando la _set_output_format funzione , è possibile impostare il numero di cifre visualizzate su tre per garantire la compatibilità con le versioni precedenti con il codice scritto per Visual Studio 2013 e versioni precedenti.

Importante

Poiché il %n formato è intrinsecamente non sicuro, è disabilitato per impostazione predefinita. Se %n viene rilevato in una stringa di formato, viene richiamato il gestore di parametri non validi, come descritto in Convalida dei parametri. Per abilitare il %n supporto, vedere _set_printf_count_output.

Direttive flag

Il primo campo facoltativo in una specifica di conversione contiene direttive flag. Questo campo contiene zero o più caratteri flag che specificano la giustificazione dell'output e controllano l'output di segni, spazi vuoti, zeri iniziali, punti decimali e prefissi ottali ed esadecimali. In una specifica di conversione possono apparire più direttive flag e i caratteri flag possono essere visualizzati in qualsiasi ordine.

Caratteri flag

Flag	significato	Predefiniti
-	Allinea a sinistra il risultato entro la larghezza del campo specificata.	Allinea a destra.
+	Usare un segno (+ o -) per anteporre il valore di output se è di un tipo firmato.	Il segno viene visualizzato solo per i valori con segno negativo (-).
0	Se la larghezza è preceduta da 0, gli zeri iniziali vengono aggiunti finché non viene raggiunta la larghezza minima. Se entrambi 0 e - vengono visualizzati, l'oggetto 0 viene ignorato. Se 0 viene specificato per un formato integer (i, u, xX, od) ed è presente anche una specifica di precisione, ad esempio, %04.dviene 0 ignorato. Se 0 viene specificato per il formato a a virgola mobile o A , gli zeri iniziali vengono anteporti alla mantissa, dopo il 0x prefisso o 0X .	Nessun riempimento.
blank (' ')	Usare un valore vuoto per anteporre il valore di output se è firmato e positivo. Lo spazio viene ignorato se appaiono sia il flag blank sia il flag +.	Non viene visualizzato alcuno spazio.
#	Quando viene usato con il oformato , xo X , il # flag usa 0rispettivamente , 0xo , per 0Xanteporre qualsiasi valore di output diverso da zero.	Non viene visualizzato alcun prefisso.
	Quando viene usato con il eformato , E, f, F, ao A , il # flag impone al valore di output di contenere un separatore decimale.	Il separatore decimale viene visualizzato solo se è seguito da cifre.
	Quando viene usato con il g formato o G , il # flag forza il valore di output a contenere un separatore decimale e impedisce il troncamento degli zeri finali. Ignorato quando viene usato con c, id, , uo s.	Il separatore decimale viene visualizzato solo se è seguito da cifre. Gli zeri finali vengono troncati.

Specifica della larghezza

In una specifica di conversione, il campo facoltativo di specifica della larghezza viene visualizzato dopo qualsiasi carattere flag. L'argomento width è un numero intero decimale non negativo che controlla il numero minimo di caratteri restituiti. Se il numero di caratteri nel valore di output è inferiore alla larghezza specificata, vengono aggiunti spazi a sinistra o a destra dei valori, a seconda che sia specificato o meno il flag di allineamento a sinistra (-), fino a raggiungere la larghezza minima. Se width è preceduto da 0, gli zeri iniziali vengono aggiunti a conversioni intere o a virgola mobile finché non viene raggiunta la larghezza minima, tranne quando la conversione è in un infinito o NaN.

La specifica della larghezza non provoca mai il troncamento di un valore. Se il numero di caratteri nel valore di output è maggiore della larghezza specificata o se width non viene specificato, vengono restituiti tutti i caratteri del valore, soggetti alla specifica di precisione.

Se la specifica della larghezza è un asterisco (*), il valore è fornito da un argomento int dall'elenco degli argomenti. L'argomento width deve precedere il valore formattato nell'elenco di argomenti, come illustrato in questo esempio:

printf("%0*d", 5, 3); /* 00003 is output */

Un valore mancante o piccolo width in una specifica di conversione non causa il troncamento di un valore di output. Se il risultato di una conversione è più ampio del width valore, il campo si espande per contenere il risultato della conversione.

Specifica della precisione

In una specifica di conversione, il terzo campo facoltativo è la specifica di precisione. È costituito da un punto (.) seguito da un numero intero decimale non negativo che, a seconda del tipo di conversione, specifica il numero di caratteri stringa, il numero di posizioni decimali o il numero di cifre significative da restituire.

A differenza della specifica della larghezza, la specifica della precisione può causare il troncamento del valore di output o l'arrotondamento di un valore a virgola mobile. Se precision viene specificato come 0 e il valore da convertire è 0, il risultato non restituisce alcun output di caratteri, come illustrato in questo esempio:

printf( "%.0d", 0 ); /* No characters output */

Se la specifica della precisione è un asterisco (*), il valore viene specificato da un argomento int dell'elenco degli argomenti. Nell'elenco degli argomenti, l'argomento precision deve precedere il valore da formattare, come illustrato nel seguente esempio:

printf( "%.*f", 3, 3.14159265 ); /* 3.142 output */

Il type carattere determina l'interpretazione di precision o la precisione predefinita quando precision viene omesso, come illustrato nella tabella seguente.

Impatto dei valori di precisione sul tipo

Type	Significato	Predefiniti
a, A	La precisione indica il numero di cifre dopo il punto.	La precisione predefinita è 13. Se la precisione è 0 non viene stampato alcun separatore decimale, a meno che non venga usato il flag #.
c, C	La precisione non ha alcun effetto.	Viene stampato il carattere.
d, i, o, u, xX	La precisione specifica il numero minimo di cifre da stampare. Se il numero di cifre nell'argomento è minore di precisione, il valore di output viene riempito a sinistra con zeri. Il valore non viene troncato quando il numero di cifre supera la precisione.	La precisione predefinita è 1.
e, E	La precisione specifica il numero di cifre da stampare dopo il separatore decimale. L'ultima cifra stampata viene arrotondata.	La precisione predefinita è 6. Se la precisione è 0 o il punto (.) viene visualizzato senza un numero successivo, non viene stampato alcun separatore decimale.
f, F	Il valore di precisione specifica il numero di cifre dopo il separatore decimale. Se viene visualizzato un separatore decimale, prima di esso viene visualizzata almeno una cifra. Il valore viene arrotondato al numero di cifre appropriato.	La precisione predefinita è 6. Se la precisione è 0 o se il punto (.) viene visualizzato senza un numero successivo, non viene stampato alcun separatore decimale.
g, G	La precisione specifica il numero massimo di cifre significative da stampare.	Vengono stampate sei cifre significative e gli eventuali zeri finali vengono troncati.
s, S	La precisione specifica il numero massimo di caratteri da stampare. I caratteri in eccesso rispetto al valore precisione non vengono stampati.	I caratteri vengono stampati fino a quando non viene trovato un carattere Null.

Specifica delle dimensioni dell'argomento

In una specifica di conversione il campo dimensione è un modificatore della lunghezza argomento per l'identificatore di conversione tipo. Il campo size prefisssi al campo tipo,hh , h, j, l (L minuscolo), L, tllw, z( I maiuscolo i), I32e , specificare I64le "dimensioni" dell'argomento corrispondente, long o short, a 32 bit o a 64 bit, carattere a byte singolo o carattere wide, a seconda dell'identificatore di conversione modificato. Questi prefissi di dimensioni vengono usati con i caratteri tipo nei gruppi di funzioni printf e wprintf per specificare l'interpretazione delle lunghezze degli argomenti, come mostrato nella tabella seguente. Il campo dimensione è facoltativo per alcuni tipi di argomento. Quando non viene specificato alcun prefisso, il formattatore usa argomenti di tipo Integer, ad esempio char, short, int, long firmati o non firmati, e tipi di enumerazione, ad esempio i tipi int a 32 bit e gli argomenti a virgola mobile float, double, e long double vengono usati come tipi double a 64 bit. Questo comportamento corrisponde alle regole di promozione degli argomenti predefinite per gli elenchi di argomenti variabili. Per altre informazioni sull'innalzamento di livello degli argomenti, vedere Puntini di sospensione e argomenti predefiniti nelle espressioni di postfissi. Nei sistemi a 32 bit e a 64 bit, la specifica di conversione di un argomento integer a 64 bit deve includere un prefisso di dimensione pari ll a o I64. In caso contrario, il comportamento del formattatore non sarà definito.

Alcuni tipi corrispondono a dimensioni diverse le codice a 32 bit e a 64 bit. Ad esempio, size_t ha una lunghezza pari a 32 bit nel codice compilato per x86 e a 64 bit nel codice compilato per x64. Per creare codice di formattazione indipendente dalla piattaforma per tipi a larghezza variabile, è possibile usare un modificatore di dimensioni per argomenti a larghezza variabile. Usare invece un modificatore di dimensioni degli argomenti a 64 bit e alzare in modo esplicito il tipo di argomento a larghezza variabile a 64 bit. Il modificatore di dimensioni dell'argomento specifico I di Microsoft (i maiuscolo) gestisce gli argomenti integer a larghezza variabile, ma è consigliabile modificare i modificatori specifici del tipo j, te z per la portabilità.

Prefissi di dimensioni per gli identificatori di formato printf e wprintf

Per specificare	Prefisso da usare	Con identificatore del tipo
char unsigned char	hh	d, i, o, u, x o X
short int short unsigned int	h	d, i, o, u, x o X
__int32 unsigned __int32	I32	d, i, o, u, x o X
__int64 unsigned __int64	I64	d, i, o, u, x o X
intmax_t uintmax_t	j oppure I64	d, i, o, u, x o X
long double	l (L minuscolo) o L	a, A, e, E, f, F, g o G
long int long unsigned int	l (L minuscola)	d, i, o, u, x o X
long long int unsigned long long int	ll (LL minuscolo)	d, i, o, u, x o X
ptrdiff_t	t o I (i maiuscolo)	d, i, o, u, x o X
size_t	z o I (i maiuscolo)	d, i, o, u, x o X
Carattere a byte singolo	h	c oppure C
Carattere wide	l (L minuscolo) o w	c oppure C
Stringa con caratteri a byte singolo	h	s, S o Z
Stringa di caratteri wide	l (L minuscolo) o w	s, S o Z

I tipi ptrdiff_t e size_t sono __int32 o unsigned __int32 nelle piattaforme a 32 bit e __int64 o unsigned __int64 nelle piattaforme a 64 bit. I I prefissi (i maiuscoli), j, te z accettano la larghezza dell'argomento corretta per la piattaforma.

In Visual C++, anche se long double è un tipo distinto, ha la stessa rappresentazione interna di double.

Un hc identificatore di tipo o hC è sinonimo di c funzioni printf e con C in wprintf funzioni. Un lcidentificatore di tipo , lCwc, o wC è sinonimo di C nelle printf funzioni e con c nelle wprintf funzioni. Un hs identificatore di tipo o hS è sinonimo di s funzioni printf e con S in wprintf funzioni. Un lsidentificatore di tipo , lSws, o wS è sinonimo di S nelle printf funzioni e con s in wprintf funzioni.

Nota

Specifico di Microsoft:
I I prefissi del modificatore (i maiuscolo), I32, I64e w della dimensione dell'argomento sono estensioni Microsoft e non sono compatibili con ISO C. Il h prefisso quando viene usato con i dati di tipo char e il l prefisso (L minuscolo) quando viene usato con i dati di tipo double sono estensioni Microsoft.

Vedi anche

printf, _printf_l, wprintf_wprintf_l
printf_s, _printf_s_l, wprintf_s_wprintf_s_l
printf_p Parametri posizionali