snprintf(3C)

名前 | 形式 | 機能説明 | 戻り値 | エラー | 使用法 | 使用例 | 属性 | 関連項目

名前

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*/ ...);

機能説明

printf() 関数は、標準出力ストリーム stdout 上に出力します。

fprintf() 関数は、出力ストリーム stream 上に出力します。

sprintf() 関数は、s から始まる連続したバイトを出力し、最後に NULL バイト (\0) をつけます。ユーザーは、十分な記憶領域が利用できることを確認する必要があります。

snprintf() 関数は、sprintf() に引数 n を追加したのと同等です。n には s によって参照されるバッファーサイズが指定されます。バッファーは、常に NULL バイトで終了します。

これらの各関数は、format の制御下で各引数の変換、書式化および出力を行います。format とは、初期シフトの状態 (もしあれば) で始まるか、または終わる文字列のことです。format は、以下に示す 0 個以上の指示語で構成されます。

• 通常文字。出力ストリームに単純にコピーされる

• 変換指定。各指定の結果として 0 個以上の引数を取り出す

format 引数が不十分である場合、結果は未定義です。引数が残っていて、format が使い果たされた場合、余分な引数は評価されますが、評価されたとしても無効になります。

変換は、引数リストの format のあとに続く、次の未使用の引数にではなく、n 番目の引数に適用されます。この場合、変換文字 % (後述を参照) は %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 でパディングされます。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 (下記参照)。

フィールド幅および精度の両方またはどちらか一方は、アスタリスク (*) で示すこともできます。この場合、int 型の引数によってフィールド幅または精度を指定します。フィールド幅および精度の両方またはどちらか一方を指定する引数 (もしあれば) は、変換される順番で引数の前に現れなければなりません。フィールド幅が負の値の場合、– フラグの後に正のフィールド幅を指定したように扱われます。 精度が負の値の場合は、精度を省略したように扱われます。%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 フラグは無視されます。0 フラグおよび ' フラグをともに指定すると、0 パディングの前に文字が挿入されます。他の変換では、このフラグの動作は未定義です。

変換文字

各変換文字を指定すると、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

double の引数は、[–]ddd.ddd の形式で 10 進数に変換されます。小数点付き数字 setlocale(3C) 参照) の後の桁数は、精度で指定した数です。精度が指定されていない場合は、6 とみなされます。精度を明示的に 0 に指定し、# フラグを指定しない場合、小数点付き数字は出力されません。小数点付き数字が出力されると、1 個以上の数字がその前に付きます。値は適切な桁数に丸められます。

e,E

double の引数は、[–]d.ddde±dd の形式に変換されます。小数点付き数字の前には 1 個の数字が付きます (引数が 0 でない場合はこの数字も 0 ではありません)。小数点付き数字の後には、精度で指定した数の数字が続きます。精度を指定しない場合は、6 とみなされます。精度が 0 で、# フラグを指定しない場合、小数点付き数字は出力されません。E 変換文字を使用すると、e ではなく E を数字につけて指数を示します。指数は、必ず 2 桁以上の数字です。値は適切な桁数に丸められます。

g,G

double の引数は、f または e の形式 (G 変換文字の場合は E 形式) で出力されます。精度は有効桁数を示します。明示的な精度が 0 である場合は、有効桁数が 1 桁になります。出力形式は変換される値によって決まります。変換の結果出力される指数が –4 より小さい場合、または精度以上の場合だけ、e (または E) 形式で出力されます。結果の小数部分からは後続 0 が取り除かれます。小数点付き数字は、その後に数字が続く場合だけ出力されます。

c

int の引数は、unsigned char 符号なし文字に変換され、結果のバイトが出力されます。

l (小文字のエル) を修飾子として指定した場合、wint_t 引数は、精度は付けないで、wchar_t 型の 2 つの要素の配列をポイントする引数を付けた ls 変換指定を行なった場合と同じように変換されます。最初の要素には ls 変換指定への wint_t 引数を含み、2 番目の要素には NULL ワイド文字を含みます。

C

lc と同じです。

wc

int の引数はワイド文字 (wchar_t) に変換されて出力されます。

s

引数は char 配列へのポインタにする必要があります。配列の中身が最後の NULL バイトまで書き込まれます (NULL バイトは含まない)。精度を指定すると、標準準拠のアプリケーション (standards(5) を参照) は、精度によって指定されるバイト数だけを書き込みます。また、標準準拠ではないアプリケーションは、精度によって指定された表示画面の カラム数に表示される文字列部分だけを出力します。精度を指定しないと場合は、無限とみなされ、最初の NULL バイトまでのすべてのバイトが出力されます。値が NULL の引数の変換は、未定義の結果になります。

修飾子として l (小文字のエル) を指定した場合、引数は wchar_t 型の並びへのポインタである必要があります。その並びからのワイド文字コードは、NULL ワイド文字コードに至るまでで、末尾に NULL ワイド文字コードを含まない文字に変換されます (最初のワイド文字が変換される前に、mbstate_t オブジェクトを 0 に初期化して記述された変換状態の、wcrtomb(3C) 関数への呼び出しによる結果と同じように変換されます)。 結果として生じる文字は、末尾の NULL 文字 (バイト) に至るまで (ただし、末尾には含まない) で書き込まれます。精度を指定しない場合、配列には、NULL ワイド文字を含む必要があります。精度を指定した場合、指定した文字 (バイト) 以上は書き込まれません (もしあれば、シフトシーケンスを含む)。配列が NULL ワイド文字を含む必要がある場合は、精度によって指定された文字シーケンスの長さを書き込み、関数は、一度配列の最後を過ぎたワイド文字へはアクセスを必要としません。文字の一部を書き込むことはありません。

S

ls と同じです。

ws

引数は wchar_t 配列へのポインタの文字列にする必要があります。その配列の中身が最後の NULL 文字まで書き込まれます (NULL 文字は含まない)。精度を指定すると、精度によって指定された表示画面のカラム数に表示するワイド文字列部分だけを出力します。精度を指定しない場合は無限とみなされ、最初の NULL 文字までのすべてのワイド文字が出力されます。値が NULL の引数を指定した場合の変換は、未定義の結果になります。

p

引数は void へのポインタにする必要があります。ポインタの値は、出力可能なシーケンスに変換されます。これらの文字は、scanf(3C) 関数の %p 変換で一致した文字と同じ文字である必要があります。

n

引数は、printf() 関数のうちの 1 つの呼び出しにおいて、この変換文字が指定されるまでに、出力先に書き込まれたバイト数が格納される整数へのポインタです。引数は変換されません。

%

% を出力します。引数は変換されません。全体の変換を指定するには %% にしてください。

変換指定が上記の形式のいずれにも当てはまらない場合、変換の結果は未定義となります。

浮動小数点値によって「無限」を内部的に表現している場合は、[±]Infinity が出力されます。希望した出力文字列の長さに応じて、Infinity は Infinity または Inf のどちらかになります。符号は、前述の規則に従って出力されます。

浮動小数点値によって「数でない値」を内部的に表現している場合は、 [±]NaN が出力されます。符号は、前述の規則に従って出力されます。

フィールド幅が存在していなかったり、あるいはその値が小さい場合でも、フィールドが切り捨てられることはありません。変換の結果がフィールド幅よりも広い場合は、その結果を収容できるようにフィールドが拡張されます。printf() および fprintf() によって生成される文字は、putc(3C) 関数を呼び出した場合と同じように出力されます。

ファイルの st_ctime と st_mtime フィールドは、printf() または fprintf() の正常実行への呼び出しと、同じストリーム上 の fflush(3C) または fclose(3C) あるいは exit(3C) または abort(3C) への呼び出しへの次の正常終了の呼び出しとの間で、更新するためにマークされます。

戻り値

printf()、fprintf()、および sprintf() 関数は、転送されるバイト数 (sprintf() の場合は最後の NULL バイトを除く) を返します。

snprintf() 関数はフォーマットされた文字数、つまり (バッファーに十分な大きさがある場合に) バッファーに書き込まれた文字数を返します。snprintf() への呼び出し時に n の値が 0 である場合、1 未満の指定されていない値が返されます。

出力エラーが検出された場合、各関数は負の値を返します。

エラー

printf() と fprintf() の両関数が異常終了する、または異常終了する可能性がある条件については、fputc(3C) または fputwc(3C) を参照してください。

さらに printf() のすべての形式において、以下の条件で異常終了します。

EILSEQ

有効な文字に対応しないワイド文字コードが検出された。

EINVAL

引数が足りない

さらに printf() と fprintf() は、以下の条件で異常終了します。

ENOMEM

使用可能な記憶領域が不足している

使用法

printf() 関数の呼び出しに wint_t または wchar_t 型のオブジェクトが存在する場合、これらのオブジェクトを定義するヘッダー <wchar.h> も含む必要があります。

sprintf() と snprintf() の両関数はマルチスレッドアプリケーションでは MT-Safe です。ロケール変更のために setlocale(3C) が呼び出されていない限り、マルチスレッドアプリケーションにおいて printf() および fprintf() 関数を安全に使用できます。

エスケープシーケンス

通常 printf() 関数に対する書式化文字列を入力するときには、C 言語に組み込まれている以下のエスケープシーケンスを使用します。ただし、これらのエスケープシーケンスは、printf() 関数によってではなく C コンパイラによって処理されます。

\a

ベルを鳴らして警報を出します。

\b

バックスペース。現在位置が行頭でなければ、出力位置を現在位置の 1 文字前に移動させます。

\f

フォームフィード。出力位置を次の論理ページの最初の出力位置に移動させます。

\n

改行。出力位置を次の行の行頭に移動させます。

\r

キャリッジリターン。出力位置を現在行の行頭に移動させます。

\t

水平タブ。出力位置を、現在行上の次の水平ハードタブ位置に移動させます。

\v

垂直タブ。出力位置を、垂直ハードタブ位置の始めに移動させます。

また C 言語では、次の形式の文字シーケンスがサポートされています。

---

\octal-number

---

および

---

\hex-number

---

8 進数 octal-number または 16 進数 hex-number で表す文字に変換します。たとえば、ASCII 表現の場合、文字 a は \141 として書き込まれ、文字 Z は \132 として書き込まれます。この文法は、NULL 文字 \0 を表す場合に最もよく使用されます。これは定数ゼロ (0) とまったく同等です。 通常の 8 進定数と同様に、8 進数に接頭辞ゼロが含まれていないことに注意してください。16 進数を指定するには、接頭辞の 0 を取り除いて接頭辞が x (小文字) になるようにします (大文字の X は不可です)。16 進シーケンスのサポートは、ANSI の拡張機能です。standards(5) を参照してください。

使用例

---

例 1 言語に依存する日付と時刻の形式を出力するには、以下のステートメントを使用します。




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), fclose(3C), fflush(3C), fputwc(3C), putc(3C), scanf(3C), setlocale(3C), stdio(3C), wcstombs(3C), wctomb(3C), attributes(5), environ(5), standards(5)

SunOS 5.8  最終更新日 1999年12月13日

名前 | 形式 | 機能説明 | 戻り値 | エラー | 使用法 | 使用例 | 属性 | 関連項目