manページ  — PRINTF

これらの関数は、 format 文字列による制御に従って出力を行います。 この文字列は、その後の引数 (または stdarg(3) の可変長引数機能でアクセスできる引数) を出力用に変換する方法を指定します。

この関数は、出力された文字数 (文字列への出力を終了する、最後の ‘\0’ は含まない) を返します。 snprintf() と vsnprintf() の場合のみ、 size の制限が無かったとしたら 出力されたであろう文字数 (同様に文字列の最後の ‘\0’ は含まない) を返します。

asprintf() と vasprintf() は、整形された文字列を格納するのに十分な大きさのバッファを指すポインタを *ret に設定します。 割り当てられた領域が不要になった場合は、このポインタを free(3) に渡して解放してください。 十分な領域を割り当てられない場合、 asprintf() と vasprintf() は -1 を戻し、 ret を NULL ポインタに設定します。

snprintf() と vsnprintf() は、最大で size, Ns, -1 文字だけ出力文字列に書き込みます ( size 番目の文字は終端の ‘\0’ になります)。 戻り値が size 引数以上である場合は、文字列を格納するには短かすぎたため、 出力された文字の一部が破棄されたことになります。

sprintf() と vsprintf() は、 size が無限であると仮定します。

整形文字列は、0 以上の命令から構成されています。 この命令には、出力ストリームに変更されずにコピーされる 通常文字 ( % 以外)、および 0 以上の後続の引数を取り出す変換指定があります。 それぞれの変換指定は、 % 文字から始まります。引数は、 (型拡張の後に) 変換指示子に適切に対応する必要があります。 % の後には、以下が順番に現れます。

• 後に $ が続く 10 進数文字列から構成され、 次にアクセスする引数を指定する任意のフィールド。 このフィールドを指定しないと、最後にアクセスされた 引数に続く引数が使用されます。引数には 1 から始まる番号が付きます。 書式指定文字列で、 アクセスできない引数がアクセスできる引数に点在する場合、 結果は不定になります。
• 0 個以上の以下のフラグ

  	値を "代替形式" に変換することを指定する # 文字。 c, d, i, n, p, s, および u 変換の場合、このオプションは効果を発揮しません。 o 変換の場合は、数値の精度が上がり、 出力文字列の最初の文字が 0 になります (明確な精度の 0 で 0 が出力される場合を除く)。 x 変換と X 変換の場合は、0 以外の結果の前に文字列 ‘0x’ ( X 変換の場合は ‘0X’) が付きます。 e, E, f, g, および G 変換の場合は、小数点以下がなくても小数点が結果に常に含まれます (通常の場合、小数点以下がある場合にかぎり、 変換結果に小数点が付きます)。 g および G 変換の場合は、後続の 0 が通常の場合のように結果から削除されません。
  	0 (ゼロ) 文字のパディングを指定する。 n 変換を除くすべての変換では、 変換値の左に空白ではなく 0 が付きます。数値変換 ( d, i, o, u, i, x, および X) で精度が指定されている場合、 0 フラグは無視されます。
  	負のフィールド幅を示す - フラグは変換された値がフィールド境界の左で揃えられる事を示します。 n 変換以外では、変換値の左に空白か 0 が付くのではなく、 変換値の右に空白が付きます。 - と amp;0 を両方とも指定した場合は amp;0 が無効になります。
  	空白。符号付き変換 ( d, e, E, f, g, G, および i) で作成される正の数値の前に空白が残ります。
  	+ 文字。符号付き変換で作成される数値の前に常に符号が付きます。 + と空白を両方とも指定した場合は空白が無効になります。

• 任意の 10 進数文字列。最低フィールド幅を指定します。 変換値の文字数がフィールドの幅より少ない場合は、左に空白が付いて (左揃えフラグを指定した場合は右に空白が付いて) フィールドの幅に合わせられます。
• ピリオド .amp; の次に任意の数字文字列が続く形式の精度。 数字文字列を省略した場合、精度は 0 になります。 d, i, o, u, x, および X 変換では、この精度の最低桁数が出力されます。 e, E, および f 変換では、小数点以下にこの精度の桁数が出力されます。 g および G 変換では、この精度の最大有効桁数が出力されます。 s 変換では、この精度の最大文字数が文字列から出力されます。
• オプション文字 h 。後の d, i, o, u, x, および X 変換が short int 引数か unsigned short int 引数に対応すること、または後の n 変換が short int 引数のポインタに対応することを指定します。
• オプション文字 l (小文字の L)。後の d, i, o, u, x, および X 変換が long int 引数か unsigned long int 引数のポインタに適用されること、または後の n 変換が long int 引数のポインタに対応することを指定します。
• オプション文字 ll (小文字の L が 2 つ)。後の d, i, o, u, x, および X 変換が long long int 引数か unsigned long long int 引数に対応すること、または後の n 変換が long long int 引数のポインタに対応することを指定します。
• オプション文字 q, 。後の d, i, o, u, x, および X 変換が quad int 引数か unsigned quad int 引数に対応すること、または後の n 変換が quad int 引数のポインタに対応することを指定します。
• オプション文字 L 。後の e, E, f, g, および G 変換が long double 引数に対応することを指定します。
• 適用する変換の型を指定する文字。

フィールド幅か精度、またはその両方は、アスタリスク ‘*’ 、または数字文字列の代わりに 1 つ以上の 10 進数と ‘$’ が続くアスタリスクで指定できます。この場合、 int 引数はフィールド幅か精度を提供します。 負のフィールド幅は、 正のフィールド幅が続く左揃えフラグとして扱われます。 負の精度は、欠落しているものとして扱われます。 1 つの書式命令に位置引数 (nn$) と位置以外の引数が混在している場合、 結果は未定義になります。

変換指示子とその意味は次のとおりです。

diouxX
	int 引数 (または適切な可変引数) が、符号付き 10 進 ( d と i) 、符号なし 8 進 ( o) 、符号なし 10 進 ( u) 、符号なし 16 進 ( x と X) に変換されます。 x 変換には文字 abcdef 、 X 変換には文字 ABCDEF が使用されます。 精度は、出力する最低桁数を指定します。 変換値で少ない桁しか必要ない場合は、 左に 0 が付きます。
DOU	long int 引数が、符号付き 10 進、符号なし 8 進、符号なし 10 進に、 それぞれの形式が ld, lo, および lu であるかのように変換されます。 この変換文字には問題があるので、最終的には出力されません。
eE	double 引数が丸められ、 [- ]d amp;.ddd e±dd のスタイルに変換されます。 小数点以上は 1 桁で、小数点以下の桁数は精度と等しくなります。 精度が指定されていない場合は 6 が仮定されます。 精度が 0 である場合、小数点は出力されません。 E 変換では、文字 E ( e ではない) が使用されて指数が導入されます。 指数には、最低 2 桁が常に含まれます。 値が 0 である場合、指数は 00 になります。
f	double 引数が丸められ、 [- ]ddd amp;.ddd, のスタイルで 10 進に変換されます。 小数点以下の桁数は、精度指定に等しくなります。 精度が指定されていない場合は 6 が仮定されます。 精度が 0 である場合、小数点は出力されません。 小数点が出力される場合は、小数点以上に最低 1 桁が出力されます。
gG	double 引数が、スタイル f か e ( G 変換の場合は E) で変換されます。精度は有効桁数を指定します。 精度が指定されていない場合は 6 が仮定されます。 精度が 0 である場合は 1 として扱われます。 変換後の指数が -4 より小さいか精度以上である場合は、スタイル e が使用されます。 後続の 0 は、結果の小数部から削除されます。 小数点は、小数点以下に最低でも 1 桁ある場合に出力されます。
c	int 引数が unsigned char に変換され、変換された文字が出力されます。
s	char * 引数が、文字型の配列を指すポインタ (文字列へのポインタ) とみなされます。 配列の文字は、最後のヌル文字まで出力されます ( NULL 文字は出力されません)。 精度が指定されている場合、指定された数以上は出力されないので、 NULL 文字は必要ありません。 精度が指定されていない場合、 または精度が配列のサイズ以上である場合、 配列の最後にはヌル文字が必要です。
p	void * ポインタ引数が、16 進で ‘(%#x’ か ‘%#lx’ でのように) 出力されます。
n	これまでに出力された文字数が、 int * ポインタ引数 (または可変ポインタ引数) が指定する整数に保存されます。 引数は変換されません。
%	‘%’ が出力されます。変換される引数はありません。 完全な変換指定は ‘%%’ です。

フィールド幅が存在しない場合、またはフィールド幅が小さい場合でも、 フィールドは切り捨てられません。変換結果がフィールド幅より大きい場合、 フィールドは変換結果を収容できるようになるまで拡張されます。