名前 | 形式 | 機能説明 | 戻り値 | エラー | 使用法 | 使用例 | 属性 | 関連項目 | 注意事項
#include <stdio.h>int printf(const char *restrict format, /* args*/ ...);
printf() 関数は、標準出力ストリーム stdout 上に出力します。
fprintf() 関数は、出力ストリーム stream 上に出力します。
sprintf() 関数は、s から始まる連続したバイトを出力し、最後に NULL バイト (\\0) をつけます。ユーザーは、十分な記憶領域が利用できることを確認する必要があります。
snprintf() 関数は、sprintf() に引数 n を追加したのと同等です。n には s によって参照されるバッファーのサイズが指定されます。n が 0 の場合、配列には何も書き込まれず、s はヌルポインタになる可能性もあります。そうでない場合、n-1 番目までの出力バイトが配列に書き込まれ、n 番目以降の出力バイトが破棄されます。そして、実際に配列に書き込まれたバイトの終わりにヌルバイトが書き込まれます。
これらの各関数は、format の制御下で各引数の変換、書式化および出力を行います。format とは、初期シフトの状態 (もしあれば) で始まるか、または終わる文字列のことです。format は、以下に示す 0 個以上の指示語で構成されます。
通常文字。出力ストリームに単純にコピーされる
変換指定。各指定の結果として 0 個以上の引数を取り出す
format 引数が不十分である場合、結果は未定義です。引数が残っていて、format が使い果たされた場合、余分な引数は評価されますが、使われません。
変換指定の書式 % の代わりに書式 %n$ を使用すると、変換は、引数リストの format のあとに続く、次の未使用の引数にではなく、n 番目の引数に適用されます。ここで n は [1, NL_ARGMAX] の範囲の 10 進数の整数で、引数リストにある引数の位置を示します。この機能によって、特定の言語に適切な順序で引数を選択する、書式文字列を定義できます (「使用例」参照)。
書式文字列に、変換指定の書式 %n$ が含まれる場合、引数リスト中の番号付けされた引数は、要求された回数だけ書式文字列から参照されます。
書式文字列に、変換指定の書式 % が含まれる場合、引数リスト中の各引数は 1 度だけ使用されます。
printf() 関数のすべての形式において、言語依存の小数点文字を出力文字列に挿入できます。小数点文字は、プログラムのロケール (LC_NUMERIC カテゴリ) によって定義されます。POSIX ロケールおよび小数点文字が定義されていないロケールでは、小数点文字のデフォルトはピリオド (.) です。
各変換指定は % 文字、または %n$ 文字シーケンスによって導入されます。これらの文字の後には、以下に示す (順番で) 文字列が続きます。
変換すべき次の引数を指定する、最後に $ が付いた 10 進数の文字列のフィールド (任意)。このフィールドがない場合は、最後に変換された引数の次の args が変換されます。
変換指定の意味を変更する 0 個以上の flags (順不同)。
field width の最小値 (任意)。変換された値がフィールド幅より少ないバイトである場合は、デフォルトとしてフィールド幅の左側に (以下で説明する左位置合わせフラグ (-) が指定されている場合は右側に)、空白をパディング (文字詰め) します。フィールド幅は、アスタリスク (*) (以下に説明) または 10 進数の整数の形式を取ります。
変換指定文字が s の場合、標準準拠のアプリケーション (standards(5) を参照) は、フィールド幅を、出力される場合の最小バイト数として解釈します。また、標準準拠ではないアプリケーションは、フィールド幅を、画面表示の最小カラム数として解釈します。標準準拠ではないアプリケーションに対しては、たとえば %10s とは、変換された値が 7 カラムの画面幅の場合は 右側に 3 個分の空白がパディングされることを意味します。
書式が %ws ならば、フィールド幅を画面表示の最小カラム数として解釈します。
精度を指定する precision (任意)。d、i、o、u、x、および X 変換の場合、数値の最小桁数を表します。 この場合、このフィールドの先頭は 0 でパディングされます。a、A、e、E、f および F 変換の場合、小数点文字以下の数字の桁数を表します。g および G 変換の場合、最大有効桁数を表します。また、s および S 変換の文字列からは、最大バイト数が出力されます。精度は、最初にピリオド (.) が来て、そのあとにアスタリスク (*) (以下に説明) または 10 進数の文字列 (任意) が続く形式になります。NULL の 10 進数の文字列は 0 として扱われます。精度がその他の変換指定文字で表される場合、動作は未定義です。
変換指定文字が s または S の場合、標準準拠のアプリケーション (standards(5) を参照) は、精度を、出力される場合の最大バイト数として解釈します。また、標準準拠ではないアプリケーションは、精度を、画面表示の最大カラム数として解釈します。標準準拠ではないアプリケーションに対しては、たとえば %.5s は、画面の 5 カラムに表示する文字列部分だけを出力します。完全な文字だけが書き込まれます。
%ws の場合、精度を画面表示の最大カラム数として解釈します。精度は、最初にピリオドが来て、その後に 10 進数の文字列が続く形式になります。NULL の 10 進数の文字列は 0 として扱われます。精度で指定したパディングは、フィールド幅で指定したパディングより優先されます。
長さ修飾子 (任意)。引数のサイズを指定します。
適用される変換の型を意味する conversion character (下記参照)。
フィールド幅および精度の両方またはどちらか一方は、アスタリスク (*) で示すこともできます。この場合、int 型の引数によってフィールド幅または精度を指定します。フィールド幅および精度の両方またはどちらか一方を指定する引数 (もしあれば) は、変換される順番で引数の前に現れなければなりません。フィールド幅が負の値の場合、– フラグの後に正のフィールド幅を指定したように扱われます。 精度が負の値の場合は、精度を省略したように扱われます。%n$ という形式で変換を指定している書式文字列では、フィールド幅または精度は *m$ シーケンスで示すことができます。この場合 m は、[1, NL_ARGMAX] の範囲の 10 進数の整数で、整数引数の引数リスト内 (書式引数に続く) のフィールド幅または精度の位置を示します。以下に例を示します。
printf("%1$d:%2$.*3$d:%4$.*3$d\ ", hour, min, precision, sec);
format には、番号付けされた引数指定 (つまり %n$ と *m$)、または番号付けされていない引数指定 (つまり % と *) のいずれかを含むことができます。通常、両方を指定することはできません。 唯一の例外として、%% と %n$ の形式の両方を含むことがあります。format 文字列に、番号付けされた引数と番号付けされていない引数とを、同時に指定した場合の結果は未定義です。番号付けされた引数を指定するとき、N 番目の引数を指定する場合は、最初から (N–1) 番目までの先行引数を書式文字列内で指定する必要があります。
以下に、フラグ文字とその意味を説明します。
10 進数変換 (%i、%d、%u、%f、%F、%g、または %G) の結果の整数部分が、千単位のグループ化文字でフォーマットされます。その他の変換についての動作結果は未定義です。貨幣以外のグループ化文字が使用されます。
変換の結果は、フィールド内で左詰めされます。このフラグを指定しない場合、変換の結果は右詰めされます。
符号つき変換の結果は、常に符号 (+ または –) で始まります。このフラグを指定しない場合、負の値を変換するときだけ符号で始まります。
符号つき変換の最初の文字が符号でない場合または変換の結果に文字がない場合は、結果の前に空白がおかれます。つまり、空白のフラグと + フラグを共に指定した場合、空白のフラグは無視されます。
値は代替形式に変換されます。c、d、i、s、および u 変換の場合、このフラグは影響しません。o 変換の場合、このフラグは (必要な場合には) 精度をあげて、結果の最初の数字をゼロにします。x ( または X) 変換では、0 以外の結果の前に 0x (または 0X) が追加されます。 a、A、e、E、f、F、g、および G 変換の場合、必ず、結果には小数点が付ます。小数点の後に数字が続かない場合でも小数点が付きます (このフラグが指定されていない場合、これらの変換の結果では、小数点以降の数字がある場合のみ小数点がつけられます)。g および G 変換の場合、結果から後続 0 が削除されません ( 通常は削除されます)。
d, i, o, u, x, X, a, A, e, E, f, F, g, および G 変換の場合、先行 0 を (符号または基数の後ろに) 用いて、フィールド幅をパディングします。空白がパディングされることはありません。0 フラグおよび - フラグをともに指定すると、0 フラグが無視されます。d、i、o、u、x、および X の各変換では、精度を指定すると、0 フラグは無視されます。0 フラグおよび ' フラグをともに指定すると、0 パディングの前に文字が挿入されます。他の変換では、このフラグの動作は未定義です。
次に、長さ修飾子とその意味を示します。
後続の変換文字 d、i、o、u、x、および X が signed char 型または unsigned char 型の引数に適用されることを指定します (引数は整数昇格の規則に従って昇格されますが、値は signed char または unsigned char の形式に変換されてから表示されます)。あるいは、後続の変換文字 n が signed char 型の引数へのポインタに適用されることを指定します。
後続の変換文字 d、i、o、u、x、および X が short 型または unsigned short 型の引数に適用されることを指定します (引数は整数昇格の規則に従って昇格されますが、値は short または unsigned short の形式に変換されてから表示されます)。あるいは、後続の変換文字 n が short 型の引数へのポインタに適用されることを指定します。
後続の変換文字 d、i、o、u、x、または X が long 型あるいは unsigned long 型の引数に適用されることを指定します。あるいは、後続の変換文字 n が long 型の引数へのポインタに適用されることを指定します。あるいは、後続の変換文字 c が wint_t 型の引数に適用されることを指定します。あるいは、後続の変換文字 s が wchar_t 型の引数へのポインタに適用されることを指定します。あるいは、後続の変換文字 a、A、e、E、f、F、g、または G には効果がないことを指定します。
後続の変換文字 d、i、o、u、x、または X が long long 型あるいは unsigned long long 型の引数に適用されることを指定します。あるいは、後続の変換文字 n が long long 型の引数へのポインタに適用されることを指定します。
後続の変換文字 d、i、o、u、x、または X が intmax_t 型あるいは uintmax_t 型の引数に適用されることを指定します。あるいは、後続の変換文字 n が intmax_t 型の引数へのポインタに適用されることを指定します。
後続の変換文字 d、i、o、u、x または X が size_t 型あるいは対応する符号付き整数型の引数に適用されることを指定します。あるいは、後続の変換文字 n が size_t 型の引数に対応する符号付き整数型の引数へのポインタに適用されることを指定します。
後続の変換文字 d、i、o、u、x または X が ptrdiff_t 型あるいは対応する符号なし整数型の引数に適用されることを指定します。あるいは、後続の変換文字 n が ptrdiff_t 型の引数へのポインタに適用されることを指定します。
後続の変換文字 a、A、e、E、f、F、g、または G が long double 型の引数に適用されることを指定します。
長さ修飾子を上記以外の変換文字と一緒に指定した場合、その動作は未定義です。
各変換指定文字を指定すると、0 個以上の引数が取り出されます。書式に関する引数の指定が不十分な場合の変換結果は、未定義です。書式が終了しても引数が残っている場合は、残りの引数は無視されます。
変換指定文字とその意味を以下で説明します。
int 引数は、[-]dddd の形式で符号付き 10 進数に変換されます。精度は、表示される最小桁数を指定します。変換している値を、指定した最小桁数より少ない桁数で表わすことができる場合は、その値に先行 0 をつけて拡張します。デフォルトの精度は 1 です。精度に 0 を指定して値 0 を変換すると、文字は出力されません。
unsigned int 引数は、dddd の形式で符号なし 8 進数の書式に変換されます。精度は、表示される最小桁数を指定します。変換している値を、指定した最小桁数より少ない桁数で表わすことができる場合は、その値に先行 0 をつけて拡張します。デフォルトの精度は 1 です。精度に 0 を指定して値 0 を変換すると、文字は出力されません。
unsigned int 引数は、dddd の形式で符号なし 10 進数の書式に変換されます。精度は、表示される最小桁数を指定します。変換している値を、指定した最小桁数より少ない桁数で表わすことができる場合は、その値に先行 0 をつけて拡張します。デフォルトの精度は 1 です。精度に 0 を指定して値 0 を変換すると、文字は出力されません。
unsigned int 引数は、dddd の形式で符号なし 16 進数の書式に変換されます。abcdef 文字が使用されます。精度は、表示される最小桁数を指定します。変換している値を、指定した最小桁数より少ない桁数で表せる場合は、その値に先行 0 をつけて拡張します。デフォルトの精度は 1 です。精度に 0 を指定して値 0 を変換すると、文字は出力されません。
ABCDEF 文字が abcdef 文字の代わりに使用される点を除いて、x 変換指定文字と同じ動作です。
double の引数は、[–]ddd.ddd の形式で 10 進数に変換されます。小数点文字 setlocale(3C) 参照) の後の桁数は、精度で指定した数です。精度が指定されていない場合は、6 とみなされます。精度を明示的に 0 に指定し、# フラグを指定しない場合、小数点文字は出力されません。小数点文字が出力されると、1 個以上の数字がその前に付きます。変換された値は、一般的な浮動小数点丸め方向モードに従って、指定した出力形式に合うように丸められます。変換が正確でない場合、不正確な例外が発生します。
変換文字 f の場合、無限または非数を表す double 型の引数は、変換文字 e の形式に変換されます。ただし、引数が無限の場合、変換の精度が 8 以上の場合は “infinity” または “Infinity” と表示され、そうでない場合は “inf” または “Inf” と表示されます。
変換文字 F の場合、無限または非数を表す double 型の引数は、変換文字 E の SUSv3 形式に変換されます。ただし、引数が無限の場合、変換の精度が 8 以上の場合は “INFINITY” と表示され、そうでない場合は “INF” と表示されます。
double の引数は、[–]d.ddde±dd の形式に変換されます。小数点文字の前には 1 個の数字が付きます (引数が 0 でない場合はこの数字も 0 ではありません)。小数点文字の後には、精度で指定した数の数字が続きます。精度を指定しない場合は、6 とみなされます。精度が 0 で、# フラグを指定しない場合、小数点文字は出力されません。E 変換文字を使用すると、e ではなく E を数字につけて指数を示します。指数は、必ず 2 桁以上の数字です。変換された値は、一般的な浮動小数点丸め方向モードに従って、指定した出力形式に合うように丸められます。変換が正確でない場合、不正確な例外が発生します。値は適切な桁数に丸められます。
無限または非数の値は、次のように処理されます。
変換文字 e の場合、無限を表す double 型の引数は、変換の精度が 7 以上の場合は “ ]&-]infinity” と表示され、そうでない場合は「[-]inf」と表示されます。非数を表す double 型の引数は、「[-]nan」と表示されます。変換文字 E の場合、「infinity」、「inf」、および「nan」の代わりに、それぞれ、「INFINITY」、「INF」、および「NAN」と表示されます。符号の印刷は、上記の規則に従います。
無限を表す double 型の引数は、変換の精度が 7 以上の場合は “ ]&-]Infinity” と表示され、そうでない場合は “ ]&-]Inf” と表示されます。非数を表す double 型の引数は、“ ]&-]NaN” と表示されます。符号の印刷は、上記の規則に従います。
double の引数は、f または e の形式 (G 変換文字の場合は E 形式) で出力されます。精度は有効桁数を示します。明示的な精度が 0 である場合は、有効桁数が 1 桁になります。出力形式は変換される値によって決まります。変換の結果出力される指数が –4 より小さい場合、または精度以上の場合だけ、e (または E) 形式で出力されます。結果の小数部分からは後続 0 が取り除かれます。小数点文字は、その後に数字が続く場合だけ出力されます。
無限または非数を表す double 型の引数は、変換文字 e または E の形式に変換されます。ただし、引数が無限の場合、変換の精度が 8 以上の場合は “infinity”、“INFINITY”、または “Infinity” と表示され、そうでない場合は “inf”、“INF”、または “Inf” と表示されます。
浮動小数点数を表す double 型の引数は、[-]0xh.hhhhp±d の形式に変換されます。基数点の前にある 1 桁の 16 進数 (h) は、変換された値が 0 の場合は 0 になり、そうでない場合は 1 になります。基数点の後にある 16 進数 (hhhh) の桁数は精度と同じになります。精度を指定しなかった場合、基数点の後にある 16 進数の桁数は、double 型の値を変換するときは 13 になり、long double 型の値を変換するときは 16 (x86 の場合) または 28 (SPARC の場合) になります。精度に 0 を指定し、# フラグを指定しなかった場合、10 進小数点文字は表示されません。変換文字 a の場合は文字「abcdef」が使用され、変換文字 A の場合は文字「ABCDEF」が使用されます。変換文字 A を指定した場合、「x」と「p」の代わりに、それぞれ、「X」と「P」が表示されます。指数の桁数は必ず 1 桁が表示され、2 の 10 進指数を表すのに必要な桁まで表示されます。値が 0 の場合、指数は 0 になります。
変換された値は、一般的な浮動小数点丸め方向モードに従って、指定した出力形式に合うように丸められます。変換が正確でない場合、不正確な例外が発生します。
無限または非数を表す double 型の引数は、変換文字 e または E の SUSv3 形式に変換されます。
int の引数は、unsigned char 符号なし文字に変換され、結果のバイトが出力されます。
l (小文字のエル) を修飾子として指定した場合、wint_t 引数は、精度は付けないで、wchar_t 型の 2 つの要素の配列をポイントする引数を付けた ls 変換指定を行なった場合と同じように変換されます。最初の要素には ls 変換指定への wint_t 引数を含み、2 番目の要素には NULL ワイド文字を含みます。
lc と同じです。
int の引数はワイド文字 (wchar_t) に変換されて出力されます。
引数は char 配列へのポインタにする必要があります。配列の中身が最後の NULL バイトまで書き込まれます (NULL バイトは含まない)。精度を指定すると、標準準拠のアプリケーション (standards(5) を参照) は、精度によって指定されるバイト数だけを書き込みます。また、標準準拠ではないアプリケーションは、精度によって指定された表示画面の カラム数に表示される文字列部分だけを出力します。精度を指定しないと場合は、無限とみなされ、最初の NULL バイトまでのすべてのバイトが出力されます。値が NULL の引数の変換は、未定義の結果になります。
修飾子として l (小文字のエル) を指定した場合、引数は wchar_t 型の並びへのポインタである必要があります。その並びからのワイド文字コードは、NULL ワイド文字コードに至るまでで、末尾に NULL ワイド文字コードを含まない文字に変換されます (最初のワイド文字が変換される前に、mbstate_t オブジェクトを 0 に初期化して記述された変換状態の、wcrtomb(3C) 関数への呼び出しによる結果と同じように変換されます)。 結果として生じる文字は、末尾の NULL 文字 (バイト) に至るまで (ただし、末尾には含まない) で書き込まれます。精度を指定しない場合、配列には、NULL ワイド文字を含む必要があります。精度を指定した場合、指定した文字 (バイト) 以上は書き込まれません (もしあれば、シフトシーケンスを含む)。配列が NULL ワイド文字を含む必要がある場合は、精度によって指定された文字シーケンスの長さを書き込み、関数は、一度配列の最後を過ぎたワイド文字へはアクセスを必要としません。文字の一部を書き込むことはありません。
ls と同じです。
引数は wchar_t 配列へのポインタの文字列にする必要があります。その配列の中身が最後の NULL 文字まで書き込まれます (NULL 文字は含まない)。精度を指定すると、精度によって指定された表示画面のカラム数に表示するワイド文字列部分だけを出力します。精度を指定しない場合は無限とみなされ、最初の NULL 文字までのすべてのワイド文字が出力されます。値が NULL の引数を指定した場合の変換は、未定義の結果になります。
引数は void へのポインタにする必要があります。ポインタの値は、出力可能なシーケンスに変換されます。これらの文字は、scanf(3C) 関数の %p 変換で一致した文字と同じ文字である必要があります。
引数は、printf() 関数のうちの 1 つの呼び出しにおいて、この変換文字が指定されるまでに、出力先に書き込まれたバイト数が格納される整数へのポインタです。引数は変換されません。
% を出力します。引数は変換されません。全体の変換を指定するには %% にしてください。
変換指定が上記の形式のいずれにも当てはまらない場合、変換の結果は未定義となります。
フィールド幅が存在していなかったり、あるいはその値が小さい場合でも、フィールドが切り捨てられることはありません。変換の結果がフィールド幅よりも広い場合は、その結果を収容できるようにフィールドが拡張されます。printf() および fprintf() によって生成される文字は、putc(3C) 関数を呼び出した場合と同じように出力されます。
ファイルの st_ctime と st_mtime フィールドは、printf() または fprintf() の正常実行への呼び出しと、同じストリーム上 の fflush(3C) または fclose(3C) あるいは exit(3C) または abort(3C) への呼び出しへの次の正常終了の呼び出しとの間で、更新するためにマークされます。
printf()、fprintf()、および sprintf() 関数は、転送されるバイト数 (sprintf() の場合は最後の NULL バイトを除く) を返します。
snprintf() 関数は n が十分な大きさであったと仮定した場合に s に書き込まれる (はずの) バイト数を、末尾のヌルバイト (の分) を含まない値で返します。 snprintf() への呼び出しで n の値が 0 の場合、書き込まれるバイト数を返し、このとき s はヌルポインタとすることができます。
出力エラーが検出された場合、各関数は負の値を返します。
printf() と fprintf() の両関数が異常終了する、または異常終了する可能性がある条件については、fputc(3C) または fputwc(3C) を参照してください。
さらに printf() のすべての形式において、以下の条件で異常終了します。
有効な文字に対応しないワイド文字コードが検出された。
引数が足りない
さらに printf() と fprintf() は、以下の条件で異常終了します。
使用可能な記憶領域が不足している
printf() 関数の呼び出しに wint_t または wchar_t 型のオブジェクトが存在する場合、これらのオブジェクトを定義するヘッダー <wchar.h> も含む必要があります。
通常 printf() 関数に対する書式化文字列を入力するときには、C 言語に組み込まれている以下のエスケープシーケンスを使用します。ただし、これらのエスケープシーケンスは、printf() 関数によってではなく C コンパイラによって処理されます。
ベルを鳴らして警報を出します。
バックスペース。現在位置が行頭でなければ、出力位置を現在位置の 1 文字前に移動させます。
フォームフィード。出力位置を次の論理ページの最初の出力位置に移動させます。
改行。出力位置を次の行の行頭に移動させます。
キャリッジリターン。出力位置を現在行の行頭に移動させます。
水平タブ。出力位置を、現在行上の次の水平ハードタブ位置に移動させます。
垂直タブ。出力位置を、垂直ハードタブ位置の始めに移動させます。
また C 言語では、次の形式の文字シーケンスがサポートされています。
\\octal-number
\\hex-number
printf (format, weekday, month, day, hour, min);
米国の使用法では、format は次の文字列へのポインタになります。
"%s, %s %d, %d:%.2d\ "
生成されるメッセージは次のとおりです。
Sunday, July 3, 10:02
ドイツの使用法では、format は次の文字列へのポインタになります。
"%1$s, %3$d. %2$s, %4$d:%5$.2d\ "
生成されるメッセージは次のとおりです。
Sonntag, 3. Juli, 10:02
printf("%s, %s %i, %d:%.2d", weekday, month, day, hour, min);
printf("pi = %.5f", 4 * atan(1.0));
printf("%20s%20s%20s", lastname, firstname, middlename);
次の属性については attributes(5) のマニュアルページを参照してください。
属性タイプ | 属性値 |
MT レベル | 下記参照 |
CSI | 対応済み |
インタフェースの安定性 | 標準 |
sprintf() 関数と snprintf() 関数は、「非同期シグナル安全」です。printf() 関数と fprintf() 関数は、setlocale(3C) を呼び出してロケールを変更していない限り、マルチスレッドアプリケーションで安全に使用できます。
exit(2), lseek(2), write(2), abort(3C), ecvt(3C), exit(3C), fclose(3C), fflush(3C), fputwc(3C), putc(3C), scanf(3C), setlocale(3C), stdio(3C), vprintf(3C), wcstombs(3C), wctomb(3C), attributes(5), environ(5), standards(5)
Solaris 10 より前のリリースで c89 を使用してコンパイルした 32 ビットアプリケーションでは、長さ修飾子 j を使用した場合の動作は未定義です。
n = 0 のときに snprintf() が返す値は、Solaris 10 リリースで変更されました。この変更は、SUSv3 仕様に基づいています。以前の動作は初期の SUSv2 仕様に基づいており、n = 0 のときに snprintf() が返す値は 1 よりも小さな未指定の値でした。