書式指定構文: printf および wprintf 関数

printf と wprintf 系のさまざまな関数では、書式設定文字列と省略可能な引数を受け取り、書式設定された文字のシーケンスを出力として生成します。 書式設定文字列には、0 個以上のディレクティブが含まれています。ディレクティブとは、出力する文字リテラル、または出力で引数を書式設定する方法を指定するためのエンコードされた変換指定です。 この記事では、書式設定文字列内の変換指定をエンコードするために使用する構文について説明します。 これらの関数の一覧については、「ストリーム入出力」を参照してください。

変換指定は、次に示す形式のように、省略可能なフィールドと必須フィールドで構成されます。

%[flags][width][.precision][size]type

変換指定の各フィールドには、特定の書式オプションまたは変換指定子を示す文字または数値を設定します。 必須の type フィールドには、引数に適用する変換の種類を指定します。 省略可能な flags、 width、および precision フィールドは、先頭のスペースやゼロ、揃え、表示精度などの他の形式の側面を制御します。 size フィールドには、変換される引数のサイズを指定します。

変換指定の基本的な構成は、パーセント記号と type 文字のみです。 たとえば、%s は文字の変換を指定しています。 パーセント記号の文字を出力するには、%% を使用します。 パーセント記号の後に書式設定フィールドとして意味をなさない文字が続く場合は、無効なパラメーター ハンドラーが呼び出されます。 詳細については、「 パラメーターの検証」を参照してください。

重要

セキュリティと安定性を確保するために、書式変換の仕様文字列がエンド ユーザー定義でないことを確認します。 たとえば、名前の入力をユーザーに要求し、その入力を user_name という名前の文字列変数に格納するプログラムについて検討します。 user_nameを印刷するには、次の操作を行わないでください。

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

代わりに、このように実行します。

printf( "%s", user_name );

Note

Visual Studio 2015 では、printf および scanf ファミリの関数は inline として宣言され、<stdio.h> および <conio.h> ヘッダーに移動されました。 前のコードを移行する場合は、これらの関数に関連して LNK2019 が表示される場合があります。 詳細については、Visual C++ 2003 から 2015 の変更履歴に関するページを参照してください。

type 変換指定子

type 変換指定子の文字は、対応する引数を文字、文字列、ポインター、整数、浮動小数点数のいずれの型として解釈するかを指定します。 type 文字だけが必須の変換指定フィールドで、省略可能なフィールドをその後に続けて指定します。

書式設定文字列に続く引数は、対応する type 文字と、省略可能な size プレフィックスに従って解釈されます。 文字型 char および wchar_t の変換は c または C を使用して指定し、1 バイト文字列とマルチバイトまたはワイド文字の文字列の変換は、書式設定に使用する関数に応じて s または S を使用して指定します。 c および s を使用して指定された文字引数と文字列引数は、printf ファミリの関数では char および char* として解釈され、wprintf ファミリの関数では wchar_t および wchar_t* と解釈されます。 C および S を使用して指定された文字引数と文字列引数は、printf ファミリの関数では wchar_t および wchar_t* として解釈され、wprintf ファミリの関数では char および char* と解釈されます。 この動作は Microsoft 固有です。 歴史的な理由から、 wprintf 関数は c と s を使用して wchar_t 文字を参照し、 C と S は狭い文字を指定します。

short、int、long、long long などの整数型とその unsigned のバリアントは、d、i、o、u、x、X を使用して指定します。 float、double、long double などの浮動小数点型は、a、A、e、E、f、F、g、G を使用して指定します。 size プレフィックスで変更しない場合、既定では、整数引数は int 型に強制変換され、浮動小数点引数は double 型に強制変換されます。 64 ビット システムでは、intは 32 ビットの値であるため、ll または I64 のプレフィックス size を使用しない限り、出力用に書式設定されると、64 ビット整数は切り捨てられます。 p で指定されるポインター型では、プラットフォームの既定のポインター サイズが使用されます。

Note

Microsoft 固有の仕様:
type 文字 Z、および printf 関数と wprintf 関数で使用した場合の type 文字 c、C、s、S の動作は、Microsoft の拡張機能です。 ISO C 標準では、すべての書式設定関数で、ナロー文字とナロー文字列に c と s が、ワイド文字とワイド文字列に C と S が一貫して使用されています。

type フィールドの文字

type 文字	引数	出力書式
c	文字	printf 関数で使用する場合は 1 バイト文字を指定し、wprintf 関数で使用する場合はワイド文字を指定します。
C	文字	printf 関数で使用する場合はワイド文字を指定し、wprintf 関数で使用する場合は 1 バイト文字を指定します。
d	Integer	符号付き 10 進整数。
i	Integer	符号付き 10 進整数。
o	Integer	符号なし 8 進整数。
u	Integer	符号なし 10 進整数。
x	Integer	符号なし 16 進整数。"abcdef" を使用します。
X	Integer	符号なし 16 進整数。"ABCDEF" を使用します。
e	浮動小数点数	[-]d.dddde[+|-]dd[d]という形式の符号付き値。 ここで、 d は 10 進数字、 dddd は指定された有効桁数に応じて 1 つ以上の 10 進数、既定では 6 桁で、 [d] は 出力形式 指数のサイズに応じて 2 桁または 3 桁の 10 進数です。
E	浮動小数点数	指数部の先頭が e ではなく E であることを除いて、e 形式と同じです。
f	浮動小数点数	フォーム [-]dddd.dを持つ符号付き値。ここで dddd は 1 桁以上の 10 進数です。 整数部の桁数は、その数値の絶対値によって決定され、小数部の桁数は指定された精度によって決定されます (既定値は 6 桁)。
F	浮動小数点数	無限大と NaN の出力が大文字である点を除き、 f 形式と同じです。
g	浮動小数点数	符号付きの値を、書式 f または e のうち、与えられた値および精度を表現できる短い方の書式で書式設定します。 書式 e が使用されるのは、指数部の値が -4 より小さい場合か、precision 引数の値以上の場合のみです。 末尾の 0 は切り捨てられ、小数点は 1 桁以上の小数部が続く場合にのみ表示されます。
G	浮動小数点数	指数部の先頭が e ではなく E であること (該当する場合) を除いて、g 形式と同じです。
a	浮動小数点数	[-]0xh.hhhhp[+|-]ddd 形式の符号付き 16 進数の倍精度浮動小数点値。ここで、 h.hhhh は仮数の 16 進数 (小文字を使用) で、 d は指数の 1 桁以上です。 有効桁数は、小数点より後の桁数を指定します。
A	浮動小数点数	[-]0Xh.hhhhP[+|-]dd 形式の符号付き 16 進数の倍精度浮動小数点値。ここで、 h.hhhh は仮数の 16 進数 (大文字を使用)、 d は指数の 1 桁以上です。 有効桁数は、小数点より後の桁数を指定します。
n	整数へのポインター	現時点までにストリームまたはバッファーに正常に書き込まれた文字数。 この値は、引数として指定したアドレスにある整数に格納されます。 ポイントされる整数のサイズは、引数サイズ指定のプレフィックスで指定できます。 n 指定子は既定で無効になっています。詳細については、重要なセキュリティに関するメモをご覧ください。
p	[ポインターの種類]	引数を 16 進数字のアドレスとして表示します。
s	String	printf 関数で使用する場合は 1 バイト文字またはマルチバイト文字の文字列を指定し、wprintf 関数で使用する場合はワイド文字の文字列を指定します。 文字は、最初の null 文字が現れるか、precision 値に達するまで表示されます。
S	String	printf 関数で使用する場合はワイド文字の文字列を指定し、wprintf 関数で使用する場合は 1 バイト文字またはマルチバイト文字の文字列を指定します。 文字は、最初の null 文字が現れるか、precision 値に達するまで表示されます。
Z	ANSI_STRING または UNICODE_STRING 構造体	VS 2013 以前 引数として ANSI_STRING または UNICODE_STRING 構造体のアドレスを渡すと、構造体の Buffer フィールドが指しているバッファーに含まれる文字列が表示されます。 size 修飾子のプレフィックスに w を使用して (%wZ など)、UNICODE_STRING 引数を指定します。 構造体の Length フィールドには、文字列の長さ (バイト単位) を設定する必要があります。 構造体の MaximumLength フィールドには、バッファーの長さ (バイト単位) を設定する必要があります。 ユニバーサル C ランタイム (UCRT) UCRT には、互換性のために現在維持されている既知の問題があります。 S指定子と同様に、サイズ修飾子プレフィックスのないZ指定子は、幅の狭い印刷機能 (printf など) を使用する場合はUNICODE_STRING、ワイド印刷機能 (wprintf など) を使用する場合はANSI_STRINGを参照します。 Zの代わりに、hZを使用してANSI_STRINGを指定します。 wZ (または lZ)を使用して、 UNICODE_STRINGを指定できます。 通常、type 文字 Z は、dbgPrint や kdPrint など、変換指定を使用するドライバー デバッグ関数でのみ使用します。

Visual Studio 2015 以降のバージョンでは、浮動小数点変換指定子 (a、 A、 e、 E、 f、 F、 g、 G) に対応する引数が無限、不定、または NaN の場合、書式設定された出力は C99 標準に準拠します。 書式設定された出力を次の表に示します。

値	出力
無限大	inf
クワイエット型 NaN	nan
シグナル型 NaN	nan(snan)
不定値 NaN	nan(ind)

これらの文字列には、プレフィックスとして記号を付ける場合があります。 浮動小数点の type 変換指定子文字が大文字の場合、出力も大文字で書式設定されます。 たとえば、書式指定子が %f ではなく %F の場合、無限大は inf ではなく INF のように書式設定されます。 scanf 関数は、これらの文字列も解析できるため、printf 関数と scanf 関数でこれらの値をラウンドトリップすることができます。

Visual Studio 2015 より前のバージョンでは、CRT で無限大、不定値、NaN の値の出力に対して、次のような非標準の別形式が使用されていました。

値	出力
+ 無限大	1.#INFrandom-digits
-無限大	-1.#INFrandom-digits
不定 (quiet NaN と同じ)	digit .#IND random-digits
NaN	digit .#NAN random-digits

これらの文字列は、プレフィックスとして記号が付いている可能性があり、フィールドの幅と精度に応じて書式設定が異なる場合があり、通常とは異なる効果がある場合があります。 たとえば、printf("%.2f\n", INFINITY) は 1.#J のように出力されました。これは、#INF の有効桁数が 2 桁に "丸められた" ためです。

Note

%s または %S に対応する引数、あるいは %Z に対応する引数の Buffer フィールドが null ポインターの場合は、"(null)" が表示されます。

Note

すべての指数形式で、表示される指数部の桁数の最小値は 2 です。必要な場合にのみ 3 を使用できます。 Visual Studio 2013 以前のバージョン向けに記述されたコードとの下位互換性を維持するために、_set_output_format 関数を使用して、表示される桁数を 3 に設定できます。

重要

書式 %n は本質的にセキュリティが万全でないため、既定で無効になっています。 %nが書式指定文字列で検出された場合、「パラメーターの検証で説明されているように、無効なパラメーター ハンドラーが呼び出されます。 %n のサポートを有効にするには、「_set_printf_count_output」を参照してください。

フラグ ディレクティブ

変換仕様の最初の省略可能なフィールドには、 flag ディレクティブが含まれています。 このフィールドには、0 個以上のフラグ文字が含まれており、出力の理由を指定し、符号、ブランク、先行ゼロ、小数点、および 8 進数および 16 進数のプレフィックスの出力を制御します。 変換指定には、複数のフラグ ディレクティブを設定できます。フラグは任意の順序で設定できます。

フラグ文字

フラグ	説明	既定値
-	指定されたフィールド幅内で結果を左揃えにします。	右揃えにします。
+	符号付きの場合に出力値にプレフィックスを付けるには、記号 (+ または -) を使用します。	記号は、マイナス記号 (-) 付きの値にのみ表示されます。
0	width に 0 というプレフィックスが付いている場合、最小幅に到達するまで先頭にゼロが追加されます。 0 と - の両方が表示される場合、0 は無視されます。 0 が整数形式 (i、u、x、X、o、d) で指定されて、有効桁数も指定されている場合 (%04.d など)、0 は無視されます。 0 が a または A の浮動小数点数形式で指定されている場合、0x または 0X プレフィックスの後の仮数部の先頭にゼロが付加されます。	パディングなし。
空白 (" ")	記号付きでプラスの場合に出力値にプレフィックスを付けるには、空白を使用します。 空白と + フラグの両方が表示される場合、空白は無視されます。	空白は表示されません。
#	o、x、X 形式で使用されるとき、# フラグではそれぞれ 0、0x、0X を使用し、ゼロ以外の出力値にプレフィックスを付けます。	プレフィックスは表示されません。
	e、E、f、F、a、または A 形式で使用されるとき、# フラグを使用すると、出力値に強制的に小数点が追加されます。	小数点は、数字が続く場合にのみ表示されます。
	g または G 形式が使用されるとき、# フラグは小数点を追加するように出力値に強制し、後続のゼロの切り詰めを防止します。 c、d、i、u、s と共に使用されるときは無視されます。	小数点は、数字が続く場合にのみ表示されます。 後続のゼロは切り詰められます。

幅指定

変換指定では、省略可能な幅指定フィールドを flags 文字の後に指定します。 width 引数は、出力される最小文字数を制御する負でない 10 進整数です。 出力値の文字数が指定された幅よりも小さい場合は、最小文字数に到達するまで値の左または右に空白が追加されます。左か右かは、左揃えのフラグ (-) が指定されているかどうかによって決まります。 width に 0 というプレフィックスが付けられている場合は、無限大または NaN への変換を除いて、最小文字数に到達するまで整数または浮動小数点数の変換の先頭にゼロが追加されます。

幅指定では、値の切り捨ては行われません。 出力値の文字数が指定された幅よりも大きい場合、または width が指定されていない場合は、値のすべての文字が出力され、有効桁数指定が適用されます。

幅指定がアスタリスク (*) の場合は、引数リストから int 引数によって値が提供されます。 次の例で示すように、引数リストでは、書式設定される値の前に width 引数を指定する必要があります。

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

変換指定に width の値がないか、あっても小さい場合、出力値の切り捨ては行われません。 変換の結果が width の値より大きい場合は、変換結果が含まれるようにフィールドが拡張されます。

精度指定

変換指定の 3 番目の省略可能フィールドは精度指定です。 これはピリオド (.) とそれに続く負ではない 10 進整数から構成されます。これは、変換の種類に応じて、出力される文字列の文字数、小数点以下桁数、または有効桁数を指定します。

幅指定とは異なり、精度指定では、出力値が切り捨てられることや、浮動小数点値が丸め処理される場合があります。 次の例で示すように、precision が 0 と指定され、変換される値が 0 の場合は、結果に何も出力されません。

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

精度指定がアスタリスク (*) の場合は、引数リストから int 引数によって値が提供されます。 次の例で示すように、引数リストでは、書式設定される値の前に precision 引数を指定する必要があります。

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

次の表で示すように、type 文字によって、precision の解釈、または precision が省略されている場合には既定の有効桁数が決定されます。

有効桁数の値が型に与える影響

Type	説明	既定値
a, A	有効桁数は、小数点より後の桁数を指定します。	既定の有効桁数は 13 です。 有効桁数が 0 の場合、# フラグが使用されていない限り、小数点は出力されません。
c, C	有効桁数式が無効です。	文字が印刷されます。
d、 i、 o、 u、 x、 X	有効桁数は、印刷する最小桁数を指定します。 引数の桁数が precision より少ない場合、出力値の左側が 0 で埋められます。 桁数が precision を超えても、値は切り捨てられません。	既定の有効桁数は 1 です。
e, E	有効桁数は、小数点より後の印刷する桁数を指定します。 最後に印刷される桁は丸め処理されます。	既定の有効桁数は 6 です。 precision が 0 であるか、ピリオド (.) の後に数字が続いていない場合、小数点は出力されません。
f, F	有効桁数の値は、小数点より後の桁数を指定します。 小数点が表示されたら、その前に、少なくとも 1 つの桁が表示されます。 値は、適切な桁数に丸め処理されます。	既定の有効桁数は 6 です。 precision が 0 であるか、ピリオド (.) の後に数字が続いていない場合、小数点は出力されません。
g, G	有効桁数は、印刷する最大有効桁数を指定します。	6 つの有効桁数が印刷され、後続の 0 が切り捨てられます。
s, S	有効桁数は、印刷する最大文字数を指定します。 precision を超える分の文字は出力されません。	Null 文字が見つかるまで、文字が出力されます。

引数サイズ指定

変換指定の size フィールドは、type 変換指定子の引数長さ修飾子です。 type フィールドの size フィールド プレフィックス (hh、h、j、l (小文字の L)、L、ll、t、w、z、I (大文字の i)、I32、I64) では、修飾する変換指定子に応じて、対応する引数の "サイズ" (long、short、32 ビット、64 ビット、1 バイト、またはワイド文字) を指定します。 次の表に示すように、printf 系の関数および wprintf 系の関数では、これらのサイズ プレフィックスを type 文字と共に使用して、引数のサイズの解釈を指定できます。 一部の引数型においては、size フィールドは省略可能です。 サイズ プレフィックスを指定しない場合、フォーマッタは整数の引数 (たとえば、符号付きまたは符号なしの char、short、int、long および列挙型) を 32 ビットの int 型として使用します。また、浮動小数点引数 float、double、および long double を 64 ビットの double 型として使用します。 この動作は、可変引数リストの既定の引数の昇格規則と一致します。 引数の昇格の詳細については、「後置式」の「省略記号と既定の引数」に関するページを参照してください。 32 ビット システムと 64 ビット システムの両方で、64 ビット整数の引数の変換指定には ll または I64 のサイズ プレフィックスを含める必要があります。 それ以外の場合はフォーマッタの動作は未定義になります。

32 ビットおよび 64 ビットのコードでは、一部の型のサイズは異なります。 たとえば、 size_t は x86 用にコンパイルされたコードでは 32 ビットですが、 x64 用にコンパイルされたコードでは 64 ビットになります。 可変幅の型がプラットフォームに依存しない書式設定コードを作成するには、可変幅引数サイズ修飾子を使用します。 代わりに、64 ビットの引数サイズ修飾子を使用して、可変幅引数の型を明示的に 64 ビットに昇格させます。 Microsoft 固有の I (大文字の i) 引数サイズ修飾子では可変幅の整数の引数を処理しますが、移植性を考慮して、型に固有の j、t、z 修飾子を使用することをお勧めします。

printf および wprintf 書式指定子のサイズ プレフィックス

指定する型	プリフィックス	型指定子
char unsigned char	hh	d、i、o、u、x、または X
short int short unsigned int	h	d、i、o、u、x、または X
__int32 unsigned __int32	I32	d、i、o、u、x、または X
__int64 unsigned __int64	I64	d、i、o、u、x、または X
intmax_t uintmax_t	j または I64	d、i、o、u、x、または X
long double	l (小文字の L) または L	a、A、e、E、f、F、g、または G
long int long unsigned int	l (小文字の L)	d、i、o、u、x、または X
long long int unsigned long long int	ll (小文字の LL)	d、i、o、u、x、または X
ptrdiff_t	t または I (大文字の i)	d、i、o、u、x、または X
size_t	z または I (大文字の i)	d、i、o、u、x、または X
1 バイト文字	h	c または C
ワイド文字	l (小文字の L) または w	c または C
1 バイト文字の文字列	h	s、 S、または Z
ワイド文字列の文字列	l (小文字の L) または w	s、 S、または Z

型 ptrdiff_t と size_t は、32 ビット プラットフォーム上では __int32 または unsigned __int32、64 ビット プラットフォーム上では __int64 または unsigned __int64 です。 サイズ プレフィックス I (大文字の i)、j、t、z は、プラットフォームに適切な引数の幅を受け取ります。

Visual C++ では、long double は別個の型ですが、これには double と同じ内部表現があります。

hc または hC の型指定子は、printf 関数の c および wprintf 関数の C と同じ意味です。 lc、lC、wc、または wC の型指定子は、printf 関数の C および wprintf 関数の c と同じ意味です。 hs または hS の型指定子は、printf 関数の s および wprintf 関数の S と同じ意味です。 ls、lS、ws、または wS の型指定子は、printf 関数の S および wprintf 関数の s と同じ意味です。

Note

Microsoft 固有の仕様:
引数サイズ修飾子 I (大文字の i)、I32、I64、w は、Microsoft の拡張機能であり、ISO C と互換性がありません。 プレフィックス h (char 型のデータと共に使用する場合)、および l (L の小文字) プレフィックス (double 型のデータと共に使用する場合) は、Microsoft の拡張機能です。

関連項目

printf、 _printf_l、 wprintf、 _wprintf_l
printf_s、 _printf_s_l、 wprintf_s、 _wprintf_s_l
printf_p 位置指定パラメーター