printf、fprintf、sprintf、snprintf、wsprintf、vprintf、vfprintf、vsprintf、vwsprintf、または vdprintf サブルーチン

オンライン編集

目的

定様式出力を印刷します。

ライブラリー

標準 C ライブラリー (libc.a) または標準 C ライブラリー (128 ビット長のダブルスを含む) (libc128.a)

構文

#include <stdio.h>

int printf (Format, [Value, ...])
const char *Format;

int fprintf (Stream, Format, [Value, ...])
FILE *Stream;
const char *Format;

int sprintf (String, Format, [Value, ...])
char *String;
const char *Format;

int snprintf (String, Number, Format, [Value, . . .])
char *String;
int Number;
const char *Format;
#include <stdarg.h>

int vprintf (Format, Value)
const char *Format;
va_list Value;

int vfprintf (Stream, Format, Value)
FILE *Stream;
const char *Format;
va_list Value;

int vsprintf (String, Format, Value)
char *String;
const char *Format;
va_list Value;

int vdprintf (fildes, Format, Value);
int fildes;
const char *Format;
va_list Value;
#include <wchar.h>

int vwsprintf (String, Format, Value)
wchar_t *String;
const char *Format;
va_list Value;

int wsprintf (String, Format, [Value, ...])
wchar_t *String;
const char *Format;

説明

printf サブルーチンは、 Format パラメーターの制御下で、 Value パラメーター値を変換し、フォーマットし、標準出力ストリームに書き込みます。 printf サブルーチンは、コード・ポイントおよび wchar_t ワイド文字コードを処理するための変換タイプを提供します。

fprintf サブルーチンは、 Format パラメーターの制御下で、 Value パラメーター値を変換し、フォーマットし、 Stream パラメーターによって指定された出力ストリームに書き込みます。 このサブルーチンは、コード・ポイントおよび wchar_t ワイド文字コードを処理するための変換型を提供します。

sprintf サブルーチンは、 Format パラメーターの制御下にある Value パラメーター値を、 String パラメーターによって指定されたアドレスから始まる連続バイトに変換し、フォーマット設定し、保管します。 sprintf サブルーチンは、ヌル文字 (¥ 0) を末尾に置きます。 フォーマットされたストリングを入れるのに十分なストレージ・スペースが使用可能であることを確認する必要があります。 このサブルーチンは、コード・ポイントおよび wchar_t ワイド文字コードを処理するための変換型を提供します。

snprintf サブルーチンは、 Format パラメーターの制御下にある Value パラメーター値を、 String パラメーターによって指定されたアドレスから始まる連続バイトに変換し、フォーマット設定し、保管します。 snprintf サブルーチンは、ヌル文字 (¥ 0) を末尾に置きます。 フォーマットされたストリングを入れるのに十分なストレージ・スペースが使用可能であることを確認する必要があります。 このサブルーチンは、コード・ポイントおよび wchar_t ワイド文字コードを処理するための変換型を提供します。 snprintf サブルーチンは、 Number パラメーターを追加した sprintf サブルーチンと同じです。このパラメーターは、 String パラメーターによって参照されるバッファーのサイズを示します。

wsprintf サブルーチンは、 Format パラメーターの制御下にある Value パラメーターの値を、 String パラメーターで指定されたアドレスから始まる連続した wchar_t 文字に変換し、フォーマット設定し、保管します。 wsprintf サブルーチンは、ヌル文字 (¥ 0) を末尾に置きます。 呼び出しプロセスは、フォーマットされたストリングを入れるために十分なストレージ・スペースが使用可能であることを確認する必要があります。 フィールド幅の単位は、 wchar_t 文字数として指定されます。 wsprintf サブルーチンは、 printf サブルーチンと同じです。ただし、 wsprintf サブルーチンの String パラメーターは、 wchar_t ワイド文字コードのストリングを使用します。

上記のサブルーチンはすべて、 varargs マクロの可変長引数機能を使用して _doprnt サブルーチンを呼び出すことによって機能します。

vdprintf、 vprintf、 vfprintf、 vsprintf、および vwsprintf サブルーチンは、 varargs マクロ・パラメーター・リストのフォーマット設定と書き込みを行います。 これらのサブルーチンは、それぞれ drpintf、 printf、 fprintf、 sprintf、 snprintf、および wsprintf サブルーチンと同じですが、パラメーターの変数番号で呼び出されない点が異なります。 代わりに、 varargs マクロによって定義されたパラメーター・リスト・ポインターを使用して呼び出されます。

注: IBM® AIX® 6 (テクノロジー・レベル 7 適用) および IBM AIX 7 (テクノロジー・レベル 1 適用)以降、浮動小数点変換ルーチン、printf および scanf 関数ファミリーの精度が、倍精度および long double 値用に 17 桁から 37 桁に増加しました。

パラメーター

Number
コピーまたは変換するストリングのバイト数を指定します。
VALUE
Format パラメーター内のオブジェクトに直接マップする 0 個以上の引数を指定します。
stream
出力ストリームを指定します。
STRING
開始アドレスを指定します。
Format
以下の 2 つのタイプのオブジェクトを含む文字ストリング。
  • プレーン文字。出力ストリームにコピーされます。
  • 変換指定。それぞれの指定により、0 個以上の項目が Value パラメーター・リストから取得されます。 vprintf、 vfprintf、 vsprintf、および vwsprintf サブルーチンの場合、各変換指定により、 varargs マクロ・パラメーター・リストから 0 個以上の項目が取り出されます。

    Value パラメーター・リストに Format パラメーターに十分な項目が含まれていない場合、結果は予測できません。 Format パラメーター全体が処理された後にさらにパラメーターが残っている場合、サブルーチンはそれらを無視します。

    Format パラメーターの各変換指定には、以下の要素があります。

  • % (パーセント記号)。
  • 0 個以上のオプション。変換指定の意味を変更します。 オプションの文字と意味は、以下のとおりです。
    '
    i、 d、 u、 f、 g 、および G の 10 進数変換の結果の整数部分を、 千ands_sep グループ化文字を使用してフォーマットします。 その他の変換の場合、動作は未定義です。 このオプションは、非通貨グループ化文字を使用します。
    -
    フィールド内の変換結果を左寄せにします。
    +
    符号付き変換の結果を + (正符号) または-(負符号) で開始します。
    スペース文字
    符号付き変換の先頭文字が符号でない場合は、結果にスペース文字を接頭部として付けます。 スペース文字と + オプション文字の両方が表示される場合、スペース文字オプションは無視されます。
    #
    値を代替形式に変換します。 c、 d、 s、および u 変換の場合、このオプションは無効です。 o 変換の場合、結果の最初の桁が強制的に 0 になるように精度が向上します。 x および X 変換の場合、ゼロ以外の結果には 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 オプションと ' オプションの両方が表示される場合、フィールドに埋め込みが行われる前にグループ化文字が挿入されます。 その他の変換の場合、結果は信頼できません。
    B
    ノーオペレーション文字を指定します。
    N
    ノーオペレーション文字を指定します。
    J
    ノーオペレーション文字を指定します。
  • 最小フィールド幅を指定するオプションの 10 進数ストリング。 変換された値の文字数がフィールド幅より少ない場合、 フィールド幅で指定された長さになるようにフィールドの左側が埋め込まれます。 - (左寄せ) オプションを指定すると、フィールドの右側に埋め込みが行われます。
  • オプションの精度。 精度は です。 (ドット) の後に 10 進数ストリングが続きます。 精度が指定されていない場合、デフォルト値は 0 です。 精度は、以下の制限を指定します。
    • d、 i、 o、 u、 x、または X の変換で表示される最小桁数。
    • e、 E、および f 変換で小数点の後に表示される桁数。
    • g 変換および G 変換の有効数字の最大数。
    • s 変換および S 変換でストリングから出力される最大バイト数。
    • S 変換から出力される、 wchar_t 配列から変換される最大バイト数。 完全な文字のみが印刷されます。
  • オプションの l (小文字の L)、 ll (小文字の LL)、 h、または L 指定子は、以下のいずれかを示します。
    • オプションの h 。後続の d、 i、 u、 o、 x、または X 変換指定子が short int または unsigned short int Value パラメーターに適用されることを指定します (パラメーターは整数プロモーションに従ってプロモートされます)。 その値は、印刷前に short int または unsigned short int に変換されます。
    • オプションの h 。後続の n 変換指定子が short int パラメーターへのポインターに適用されることを指定します。
    • オプションの l (小文字の L) は、後続の d、 i、 u、 o、 x、または X 変換指定子が long int または unsigned long int パラメーターに適用されることを指定します。
    • オプションの l (小文字の L)。後続の n 変換指定子が long int パラメーターへのポインターに適用されることを指定します。
    • オプションの ll (小文字の LL) は、後続の d、 i、 u、 o、 x、または X 変換指定子が long long int または unsigned long long int パラメーターに適用されることを指定します。
    • オプションの ll (小文字の LL)。後続の n 変換指定子が long long int パラメーターへのポインターに適用されることを指定します。
    • オプションの L 。後続の e、 E、 f、 g、または G 変換指定子が long double パラメーターに適用されることを指定します。 libc.aとリンクされている場合、 long double は double (64bits) と同じです。 libc128.a および libc.aとリンクされている場合、 long double は 128 ビットです。
  • オプションの H、 D、または DD 指定子は、以下のいずれかの変換を示します。
    • オプションの H 。 e、 E、 f、 F、 g、または G 変換指定子が _Decimal32 パラメーターに適用されることを指定します。
    • 後続の e、 E、 f、 F、 g、または G 変換指定子が _Decimal64 パラメーターに適用されることを指定するオプションの D 。
    • 後続の e、 E、 f、 F、 g、または G 変換指定子が _Decimal128 パラメーターに適用されることを指定するオプションの DD 。
  • オプションの vl、 lv、 vh、 hv または v 指定子は、以下のいずれかのベクトル・データ型変換を示します。
    • オプションの v 。これは、 e、 E、 f、 g、 G、 a、または A 変換指定子が vector float パラメーターに適用されることを指定します。 1 つの引数を使用し、データを一連の 4 つの 4 バイト浮動小数点コンポーネントとして解釈します。
    • 後続の c、 d、 i、 u、 o、 x、または X 変換指定子が vector signed char、 vector unsigned char、または vector bool char パラメーターに適用されることを指定するオプションの v 。 引数を 1 つ取り込み、そのデータを一連の 16 個の 1 バイト・コンポーネントとして解釈します。
    • オプションの vl または lv 。後続の d、 i、 u、 o、 x、または X 変換指定子が vector signed int、 vector unsigned int、または vector bool パラメーターに適用されることを指定します。 引数を 1 つ取り込み、そのデータを一連の 4 個の 4 バイト整数コンポーネントとして解釈します。
    • オプションの vh または hv 。これは、 d、 i、 u、 o、 x、または X 変換指定子が vector signed short または vector unsigned short パラメーターに適用されることを指定します。 引数を 1 つ取り込み、そのデータを一連の 8 個の 2 バイト整数コンポーネントとして解釈します。
    • 上記の指定子のいずれについても、ベクトル・サイズ指定子の直前にオプションの区切り文字を指定することができます。 分離文字が指定されていない場合、変換が cでない限り、デフォルトの分離文字はスペースです。この場合、デフォルトの分離文字はヌルです。 サポートされるオプションの分離文字セットは、 , (コンマ)、 ; (セミコロン)、 : (コロン)、および _ (下線) です。
  • 以下の文字は、適用される変換のタイプを示します。
    %
    変換を行いません。 印刷 (%)。
    d または i
    整数を指定する Value パラメーターを受け入れ、それを符号付き 10 進表記に変換します。 精度は、表示する最小桁数を指定します。 変換される値がより少ない桁数で表現できる場合は、先行 0 で拡張されます。 デフォルトの精度は 1 です。 精度が 0 の値を変換した結果は、ヌル・ストリングになります。 先行文字として 0 を使用してフィールド幅を指定すると、フィールド幅の値に先行 0 が埋め込まれます。
    u
    符号なし整数を指定する Value パラメーターを受け入れ、符号なし 10 進表記に変換します。 精度は、表示する最小桁数を指定します。 変換される値がより少ない桁数で表現できる場合は、先行 0 で拡張されます。 デフォルトの精度は 1 です。 精度が 0 の値を変換した結果は、ヌル・ストリングになります。 先行文字として 0 を使用してフィールド幅を指定すると、フィールド幅の値に先行 0 が埋め込まれます。
    O
    符号なし整数を指定する Value パラメーターを受け入れ、それを符号なし 8 進表記に変換します。 精度は、表示する最小桁数を指定します。 変換される値がより少ない桁数で表現できる場合は、先行 0 で拡張されます。 デフォルトの精度は 1 です。 精度が 0 の値を変換した結果は、ヌル・ストリングになります。 先行文字としてフィールド幅に 0 を指定すると、フィールド幅の値に先行 0 が埋め込まれます。 フィールド幅の 8 進数値は暗黙指定されません。
    x または X
    符号なし整数を指定する Value パラメーターを受け入れ、符号なし 16 進表記に変換します。 文字 abcdef は x 変換に使用され、文字 ABCDEF は X 変換に使用されます。 精度は、表示する最小桁数を指定します。 変換される値がより少ない桁数で表現できる場合は、先行 0 で拡張されます。 デフォルトの精度は 1 です。 精度が 0 の値を変換した結果は、ヌル・ストリングになります。 先行文字として 0 を使用してフィールド幅を指定すると、フィールド幅の値に先行 0 が埋め込まれます。
    F
    double を指定する Value パラメーターを受け入れ、[-]ddd.dddの形式の 10 進表記に変換します。 小数点以下の桁数は、精度指定と等しくなります。 精度が指定されていない場合は、6 桁が出力されます。 精度が 0 の場合、小数点は表示されません。
    e または E
    double を指定する Value パラメーターを受け入れ、それを指数形式 [-]d.ddde+/-ddに変換します。 小数点の前に 1 桁あり、小数点の後の桁数は精度指定と等しくなります。 精度の指定は、0 から 17 桁の範囲にすることができます。 精度が指定されていない場合は、6 桁が出力されます。 精度が 0 の場合、小数点は表示されません。 E 変換文字は、指数の前に e ではなく E の数値を生成します。 指数には少なくとも 2 桁が必ず含まれます。
    g または G
    倍精度を指定する Value パラメーターを受け入れ、有効数字の桁数を指定する精度で、 e、 E、または f 変換文字のスタイルに変換します。 末尾の 0 は結果から削除されます。 小数点は、その後に数字が続いている場合にのみ表示されます。 使用されるスタイルは、変換される値によって左右されます。 Style e (E, if G is the flag used) results only if the exponent resulting from the conversion is less than -4, or if it is greater or equal to the precision. 明示的な精度が 0 の場合は、1 と見なされます。
    C
    unsigned char データ型に変換された整数を指定する Value パラメーターを受け入れ、出力します。
    C
    wchar_t ワイド文字コードを指定する Value パラメーターを受け入れ、印刷します。 Value パラメーターで指定された wchar_t ワイド文字コードは、文字を表すバイトの配列に変換され、その文字が書き込まれます。 wsprintf サブルーチンを使用すると、 Value パラメーターは変換されずに書き込まれます。
    s
    Value パラメーターをストリング (文字ポインター) として受け入れ、ヌル文字 (¥ 0) が検出されるか、精度によって示されたバイト数に達するまで、ストリングからの文字が出力されます。 精度を指定しないと、最初のヌル文字までのすべてのバイトが印刷されます。 Value パラメーターで指定されたストリング・ポインターが NULL 値の場合、結果は信頼できません。
    S
    対応する Value パラメーターを wchar_t ストリングへのポインターとして受け入れます。 ストリングの文字は、ヌル文字 (¥ 0) が検出されるか、精度で示されたワイド文字の数に達するまで (変換なしで) 印刷されます。 精度を指定しない場合には、最初の null 文字までのすべての文字が表示されます。 Value パラメーターで指定されたストリング・ポインターの値が NULL の場合、結果は信頼できません。
    p
    void を指すポインターを受け入れます。 ポインターの値は、符号なし 16 進数 (x) と同じ、印刷可能文字のシーケンスに変換されます。
    n
    この呼び出しによって出力ストリームに書き込まれる文字数 ( wsprintf サブルーチンの場合は、ワイド文字コード) が書き込まれる整数へのポインターを受け入れます。 引数は変換されません。
 

フィールドの幅または精度は、数字ストリングの代わりに * (アスタリスク) で示すことができます。 この場合、整数の Value パラメーターでフィールドの幅または精度を指定します。 出力用に変換された Value パラメーターは、変換文字に達するまで検索されません。したがって、フィールド幅または精度を指定するパラメーターは、変換される値 (ある場合) の前になければなりません。

変換の結果がフィールド幅より広い場合、フィールドは変換された結果を含むように拡張され、切り捨ては行われません。 ただし、フィールドの幅または精度が小さいと、右側が切り捨てられることがあります。

printf、 fprintf、 sprintf、 snprintf、 wsprintf、 vprintf、 vfprintf、 vsprintf、または vwsprintf サブルーチンによって、言語ラジックスに依存する文字を挿入できます。 基数文字は、プログラムのロケールの LC_NUMERIC カテゴリーの言語固有のデータによって定義されます。 C ロケール、または基数文字が定義されていないロケールでは、基数文字はデフォルトで a になります。 (ドット) で現行作業行を指定します。

これらのサブルーチンのいずれかが正常に実行された後、同じストリームまたは exit または abort サブルーチンに対する fclose または fflush サブルーチンの呼び出しが次に正常に完了する前に、st_ctimeおよびst_mtimeファイルのフィールドに更新のマークが付けられます。

e、 E、 f、 g、および G 変換指定子は、以下のように特殊浮動小数点値を表します。

項目 説明
静止 NaN +NaNQまたは-NaNQ
シグナル NaN +NaNSまたは-NaNS
+/-INF (+ /-INF) + INF または -INF
+/-0 +または-0

+ (正符号) の表記は、 + またはスペース文字フォーマット・オプションが指定されているかどうかによって異なります。

これらのサブルーチンは、システムがパラメーター・リストのエレメントを可変順序で処理できるようにするフォーマット・ストリングを処理することができます。 このような場合、通常の変換文字% (パーセント記号) は %digit$に置き換えられます。ここで、 digit は 1 から NL_ARGMAX 値までの 10 進数です。 その後、変換は、次の未使用引数ではなく、指定された引数に適用されます。 この機能は、特定の言語に適した順序で書式制御ストリングを定義します。 変数の順序付けを使用する場合、精度のフィールド幅の * (アスタリスク) 指定は、 %digit$に置き換えられます。 変数順序付けフィーチャーを使用する場合は、すべての変換に対してそのフィーチャーを指定する必要があります。

以下の基準が適用されます。

  • NLS 拡張機能に渡されるフォーマットには、変換のフォーマット、または明示的または暗黙的な引数番号のいずれかを含めることができます。 ただし、%% (二重パーセント記号) を除き、これらの形式を単一の書式制御ストリング内で混在させることはできません。
  • n 値には、先行ゼロがあってはなりません。
  • %n$ を使用する場合は、 %1$ から %n- 1$ まで (両端を含む) を使用する必要があります。
  • %n$ の n は、1 から NL_ARGMAX 値までの範囲にあります。 NL_ARGMAX 値について詳しくは、 limits.h ファイルを参照してください。
  • 引数リスト内の番号付き引数は、必要な回数だけ参照できます。
  • フィールド幅または精度の * (アスタリスク) 指定は、変数順序 %n$ 形式では許可されません。代わりに、 *m$ 形式が使用されます。

戻り値

正常終了すると、 printf、 fprintf、 vprintf、および vfprintf サブルーチンは、伝送されたバイト数 ( sprintf、および vsprintf サブルーチンの場合はヌル文字 [¥ 0] を含まない) を戻します。 エラーが発生した場合は、負の値が出力されます。

正常終了すると、 snprintf サブルーチンは String パラメーターに書き込まれたバイト数 (終了ヌル・バイトを除く) を戻します。 出力の長さが Number パラメーターを超えたために出力文字が廃棄された場合、 snprintf サブルーチンは、 Number パラメーターが十分な大きさ (終了ヌル・バイトを除く) であった場合に String パラメーターに書き込まれたバイト数を戻します。

正常終了すると、 wsprintf および vwsprintf サブルーチンは、送信されたワイド文字の数を戻します (ワイド文字のヌル文字 [¥ 0] は含みません)。 エラーが発生した場合は、負の値が出力されます。

エラー・コード

printf、 fprintf、 sprintf、 snprintf、または wsprintf サブルーチンは、 Stream パラメーターで指定されたファイルがバッファーに入れられていない場合、またはバッファーをフラッシュする必要があり、以下の 1 つ以上が該当する場合に失敗します。

項目 説明
EAGAIN O_NONBLOCK または O_NDELAY フラグは、 Stream または String パラメーターで指定されたファイルの基礎となるファイル記述子に対して設定され、プロセスは書き込み操作で遅延します。
EBADF Stream または String パラメーターによって指定されたファイルの基礎となるファイル記述子は、書き込み用にオープンされた有効なファイル記述子ではありません。
EFBIG このプロセスのファイル・サイズの制限または最大ファイル・サイズを超えるファイルに書き込もうとしました。 詳しくは、 ulimit サブルーチンを参照してください。
EINTR シグナルの受信が原因で書き込み操作が終了し、データが転送されなかったか、部分的な転送が報告されませんでした。
注: アプリケーションのバインド先のライブラリー・ルーチンによっては、このサブルーチンが EINTRを返す場合があります。 sa_restartについては、 signal サブルーチンを参照してください。
項目 説明
EIO プロセスが、その制御端末への書き込みを試行するバックグラウンド・プロセス・グループのメンバーであり、 TOSTOP フラグが設定されており、プロセスが SIGTTOU シグナルを無視もブロックもしておらず、プロセスのプロセス・グループに親プロセスがありません。
ENOSPC ファイルが入っている装置にフリー・スペースが残っていません。
EOVERFLOW

UNIX03 モードでは、Number パラメーターの値が INT_MAXの値より大きい場合、 snprintf または vsnprintf サブルーチンは失敗します。

注: XPG_SUS_ENV 環境変数の値が ON に設定されている場合、 UNIX03 動作が使用可能になります。
EPIPE どのプロセスによっても読み取りのためにオープンされていないパイプまたは先入れ先出し (FIFO) に書き込もうとしました。 SIGPIPE シグナルがプロセスに送信されます。

以下の 1 つ以上が該当する場合、 printf、 fprintf、 sprintf、 snprintf、または wsprintf サブルーチンは失敗する可能性があります。

項目 説明
EILSEQ 無効な文字シーケンスが検出されました。
EINVAL Format パラメーターが受け取った引数が不十分です。
ENOMEM 使用可能なストレージ・スペースが不十分です。
ENXIO 要求が存在しない装置で作成されたか、要求が装置の機能の範囲外でした。

例

以下の例は、 vfprintf サブルーチンを使用してエラー・ルーチンを作成する方法を示しています。

#include <stdio.h>
#include <stdarg.h>
/* The error routine should be called with the
     syntax:       */
/* error(routine_name, Format
     [, value, . . . ]); */
/*VARARGS0*/
void error(char *fmt, . . .);
/* **  Note that the function name and
     Format arguments cannot be **
     separately declared because of the **
     definition of varargs.  */  {
   va_list args;

   va_start(args, fmt);
   /*
   ** Display the name of the function
      that called the error routine   */
   fprintf(stderr, "ERROR in %s: ",
      va_arg(args, char *));   /*
   ** Display the remainder of the message
   */
   fmt = va_arg(args, char *);
   vfprintf(fmt, args);
   va_end(args);
    abort();  }