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