Namespaces
Variants

vprintf, vfprintf, vsprintf, vsnprintf, vprintf_s, vfprintf_s, vsprintf_s, vsnprintf_s

From cppreference.net
< c ‎ | io
C
File input/output
Types and objects
Direct input/output
Formatted output
vprintf vfprintf vsprintf vsnprintf vprintf_s vfprintf_s vsprintf_s vsnprintf_s
(C99) (C11) (C11) (C11) (C11)
(C95) (C95) (C95) (C11) (C11) (C11) (C11)
File positioning
Error handling
Operations on files
ヘッダーで定義 <stdio.h>
(1)
int vprintf ( const char * format, va_list vlist ) ;
(C99まで)
int vprintf ( const char * restrict format, va_list vlist ) ;
(C99以降)
(2)
int vfprintf ( FILE * stream, const char * format, va_list vlist ) ;
(C99まで)
int vfprintf ( FILE * restrict stream, const char * restrict format,
va_list vlist ) ;
(C99以降)
(3)
int vsprintf ( char * buffer, const char * format, va_list vlist ) ;
(C99まで)
int vsprintf ( char * restrict buffer, const char * restrict format,
va_list vlist ) ;
(C99以降)
int vsnprintf ( char * restrict buffer, size_t bufsz,
const char * restrict format, va_list vlist ) ;
(4) (C99以降)
int vprintf_s ( const char * restrict format, va_list vlist ) ;
(5) (C11以降)
int vfprintf_s ( FILE * restrict stream, const char * restrict format,
va_list vlist ) ;
(6) (C11以降)
int vsprintf_s ( char * restrict buffer, rsize_t bufsz,
const char * restrict format, va_list vlist ) ;
(7) (C11以降)
int vsnprintf_s ( char * restrict buffer, rsize_t bufsz,
const char * restrict format, va_list vlist ) ;
(8) (C11以降)

vlist で定義された位置からデータを読み込み、それらを文字列相当値に変換し、様々なシンクに結果を書き込みます。

1) 結果を stdout に書き込みます。
2) 結果をファイルストリーム stream に書き込みます。
3) 結果を文字列 buffer に書き込みます。
4) 結果を文字列 buffer に書き込みます。最大で bufsz - 1 文字が書き込まれます。結果の文字列は、 bufsz がゼロでない限り、ヌル文字で終端されます。 bufsz がゼロの場合、何も書き込まれず、 buffer はヌルポインタでも構いませんが、戻り値（ヌル終端文字を含まない書き込み可能バイト数）は依然として計算され返されます。
5-8) (1-4) と同様ですが、以下のエラーが実行時に検出され、現在インストールされている constraint handler 関数が呼び出されます：
  • 変換指定子 %n が format に存在する場合
  • %s に対応する引数のいずれかがnullポインタの場合
  • format または buffer がnullポインタの場合
  • bufsz がゼロまたは RSIZE_MAX より大きい場合
  • 文字列および文字変換指定子でエンコーディングエラーが発生した場合
  • （ vsprintf_s のみ）、 buffer に格納される文字列（末尾のnullを含む）が bufsz を超える場合
すべての境界チェック付き関数と同様に、 vprintf_s 、 vfprintf_s 、 vsprintf_s 、および vsnprintf_s は、実装によって __STDC_LIB_EXT1__ が定義されており、かつユーザーが <stdio.h> をインクルードする前に __STDC_WANT_LIB_EXT1__ を整数定数 1 に定義した場合にのみ利用可能であることが保証されます。

目次

翻訳の説明： - 「Contents」を「目次」に翻訳しました - HTMLタグ、属性、リンク先は一切変更していません - C++関連の用語（Parameters、Return value、Exampleなど）は原文のまま保持しています - 番号付けや書式設定は完全に維持しています

パラメータ

stream - 書き込み先の出力ファイルストリーム
buffer - 書き込み先の文字列へのポインタ
bufsz - 最大 bufsz - 1 文字まで書き込み可能（ナルターミネータ含む）
format - データの解釈方法を指定するナル終端文字列へのポインタ
vlist - 出力するデータを含む可変引数リスト

format 文字列は、出力ストリームに変更なくコピーされる通常のバイト文字（ % を除く）と変換指定子で構成されます。各変換指定子は以下の形式を持ちます：

  • 導入 % 文字。
  • (オプション) 変換の動作を変更する1つ以上のフラグ:
  • - : 変換結果がフィールド内で左揃えされます（デフォルトでは右揃え）。
  • + : 符号付き変換の場合、常に符号が変換結果の前に付加されます（デフォルトでは負の場合のみマイナス記号が付きます）。
  • space : 符号付き変換の結果が符号文字で始まらない場合、または空の場合、スペースが結果の前に付加されます。 + フラグが存在する場合は無視されます。
  • # : 変換の 代替形式 が実行されます。正確な効果については以下の表を参照してください。それ以外の場合の動作は未定義です。
  • 0 : 整数および浮動小数点数変換の場合、 space 文字の代わりに先行ゼロを使用してフィールドが埋められます。整数の場合、精度が明示的に指定されている場合は無視されます。このフラグを使用する他の変換では動作は未定義です。 - フラグが存在する場合は無視されます。
  • (オプション) 整数値または * で、最小フィールド幅を指定します。結果は、必要に応じて、右揃えの場合は左側に、左揃えの場合は右側に、 スペース 文字（デフォルト）でパディングされます。 * が使用される場合、幅は int 型の追加の引数で指定され、この引数は変換対象の引数と、精度を指定する引数（存在する場合）の前に現れます。引数の値が負の場合、 - フラグが指定され、正のフィールド幅となります（注: これは最小幅です: 値が切り詰められることはありません）。
  • (オプション) . に続く整数値、または * 、あるいは何も指定しないことで、変換の 精度 を指定します。 * が使用される場合、 精度 は int 型の追加引数によって指定されます。この引数は変換対象の引数の前に、最小フィールド幅を指定する引数（存在する場合）の後に配置されます。この引数の値が負の場合、無視されます。数値も * も使用されない場合、精度はゼロと見なされます。 精度 の正確な効果については以下の表を参照してください。
  • (オプション) 長さ修飾子 引数のサイズを指定する（変換形式指定子と組み合わせて、対応する引数の型を指定します）。
  • 変換フォーマット指定子。

以下のフォーマット指定子が利用可能です:

変換
指定子 		説明 期待される
引数の型
長さ修飾子→ hh h none l ll j z t L
C99以降でのみ利用可能→ 可 可 可 可 可
% リテラル % を書き出す。完全な変換指定は %% でなければならない。 N/A N/A N/A N/A N/A N/A N/A N/A N/A
c

単一文字 を書き込みます。

  • 引数はまず unsigned char に変換されます。
  • l 修飾子が使用される場合、引数はまず %ls による wchar_t [ 2 ] 引数の文字列変換と同様に処理されます。
N/A N/A
int
wint_t
N/A N/A N/A N/A N/A
s

文字列 を書き込みます。

  • 引数は文字配列の先頭要素へのポインタでなければなりません。
  • 精度 は書き込む最大バイト数を指定します。 精度 が指定されていない場合、最初のヌル終端文字まで（ヌル終端文字を含まない）のすべてのバイトを書き込みます。
  • l 指定子が使用される場合、引数は wchar_t 配列の先頭要素へのポインタでなければならず、変換状態をゼロ初期化した wcrtomb の呼び出しによってchar配列に変換されます。
N/A N/A
char *
wchar_t *
N/A N/A N/A N/A N/A
d
i

符号付き整数 を10進数表現 [-]dddd に変換します。

  • 精度 は表示する最小桁数を指定します。デフォルトの精度は 1 です。
  • 変換された値と精度の両方が ​ 0 ​ の場合、変換結果は文字を生成しません。
  • z 修飾子の場合、期待される引数の型は size_t の符号付きバージョンです。
signed char
short
int
long
long long
※
N/A
o

符号なし整数 を8進数表現 oooo に変換します。

  • 精度 は表示する最小桁数を指定します。デフォルトの精度は 1 です。
  • 変換された値と精度の両方が ​ 0 ​ の場合、変換結果は文字を出力しません。
  • 代替実装 では、必要に応じて精度が増加され、1つの先行ゼロが書き込まれます。その場合、変換された値と精度の両方が ​ 0 ​ の場合、単一の ​ 0 ​ が書き込まれます。
unsigned char
unsigned short
unsigned int
unsigned long
unsigned long long
ptrdiff_t の符号なしバージョン
N/A
x
X

符号なし整数 を16進数表現 hhhh に変換します。

  • x 変換では abcdef の文字が使用されます。
  • X 変換では ABCDEF の文字が使用されます。
  • 精度 は表示される最小桁数を指定します。デフォルトの精度は 1 です。
  • 変換された値と精度の両方が ​ 0 ​ の場合、変換結果は文字を出力しません。
  • 代替実装 では、変換された値が非ゼロの場合、結果に 0x または 0X が前置されます。
N/A
u

unsigned integer を10進数表現 dddd に変換します。

  • Precision は表示する最小桁数を指定します。
  • デフォルトの精度は 1 です。
  • 変換された値と精度の両方が ​ 0 ​ の場合、変換結果は文字を出力しません。
N/A
f
F (C99)

浮動小数点数 を [-]ddd.ddd スタイルの10進表記に変換します。

  • 精度 は小数点以下の表示桁数を正確に指定します。
  • デフォルトの精度は 6 です。
  • 代替実装 では、小数点以下に数字が続かない場合でも小数点が書き込まれます。
  • 無限大および非数値の変換スタイルについては 注記 を参照してください。
N/A N/A
double
double (C99)
N/A N/A N/A N/A
long double
e
E

浮動小数点数 を10進指数表記に変換します。

  • e 変換スタイルでは [-]d.ddd  e ±dd 形式が使用されます。
  • E 変換スタイルでは [-]d.ddd  E ±dd 形式が使用されます。
  • 指数部は少なくとも2桁で、必要に応じてより多くの桁が使用されます。
  • 値が ​ 0 ​ の場合、指数も ​ 0 ​ になります。
  • 精度 は小数点以下の表示桁数を指定します。
  • デフォルトの精度は 6 です。
  • 代替実装 では、後続の桁がない場合でも小数点が書き込まれます。
  • 無限大と非数の変換スタイルについては 注記 を参照してください。
N/A N/A N/A N/A N/A N/A
a
A

(C99)

浮動小数点数を16進指数表記に変換します。

  • a 変換スタイルでは [-]  0x h.hhh  p ±d 形式が使用されます。
  • A 変換スタイルでは [-]  0X h.hhh  P ±d 形式が使用されます。
  • 引数が正規化浮動小数点値の場合、最初の16進数は 0 ではありません。
  • 値が ​ 0 ​ の場合、指数も ​ 0 ​ になります。
  • 精度 は16進小数点文字の後に表示される正確な桁数を指定します。
  • デフォルトの精度は値を正確に表現するのに十分です。
  • 代替実装 では、後続する桁がなくても10進小数点文字が書き込まれます。
  • 無限大と非数の変換スタイルについては notes を参照してください。
N/A N/A N/A N/A N/A N/A
g
G

浮動小数点数 を値と 精度 に応じて10進数表記または10進指数表記に変換します。

  • g 変換スタイルの場合、 e または f スタイルでの変換が行われます。
  • G 変換スタイルの場合、 E または f (C99以前) F (C99以降) スタイルでの変換が行われます。
  • P を、精度が0でない場合はその値、精度が指定されていない場合は 6 、精度が ​ 0 ​ の場合は 1 とします。次に、 E スタイルでの変換の指数が X の場合：
    • P > X ≥ −4 の場合、変換は f または F (C99以降) スタイルで、精度は P − 1 − X となります。
    • それ以外の場合、変換は e または E スタイルで、精度は P − 1 となります。
  • 代替表現 が要求されない限り、末尾のゼロは削除され、小数部が残っていない場合は小数点も削除されます。
  • 無限大と非数の変換スタイルについては 注記 を参照してください。
N/A N/A N/A N/A N/A N/A
n

この関数呼び出しでこれまでに 書き込まれた文字数 を返します。

  • 結果は引数が指す値に 書き込まれます 。
  • 指定子には フラグ 、 フィールド幅 、または 精度 を含めることはできません。
  • z 修飾子の場合、期待される引数の型は S * であり、ここで S は size_t の符号付きバージョンです。
signed char *
short *
int *
long *
long long *
※
該当なし
p

実装定義の文字シーケンスを書き込み、 pointer を定義します。

N/A N/A
void *
N/A N/A N/A N/A N/A N/A
注記

浮動小数点変換関数は、無限大を inf または infinity に変換します。どちらが使用されるかは実装定義です。

非数は nan または nan( char_sequence ) に変換されます。どちらが使用されるかは実装定義です。

変換指定子 F , E , G , A は、代わりに INF , INFINITY , NAN を出力します。

char , unsigned char , signed char , short , および unsigned short を表示するための変換指定子は、 デフォルト引数プロモーション によってプロモートされた型を期待しますが、表示前にその値は char , unsigned char , signed char , short , および unsigned short に変換されます。可変引数関数が呼び出されるときに行われるプロモーションにより、これらの型の値を渡すことは安全です。

固定幅文字型（ int8_t など）の正しい変換指定は、ヘッダ <inttypes.h> で定義されています（ただし PRIdMAX , PRIuMAX などは %jd , %ju などのシノニムです）。

メモリ書き込み変換指定子 %n は、フォーマット文字列がユーザー入力に依存するセキュリティ攻撃の一般的な標的であり、 境界チェック付き printf_s 関数ファミリではサポートされていません (C11以降) 。

各変換指定子の動作の後には シーケンスポイント があります。これにより、複数の %n 結果を同じ変数に格納したり、エッジケースとして、同じ呼び出し内で以前の %n によって変更された文字列を表示したりすることが可能になります。

変換指定が無効な場合、動作は未定義です。

戻り値

1-3) 成功した場合は書き込まれた文字数、エラーが発生した場合は負の値。
4) 成功した場合に書き込まれた文字数、またはエラー発生時の負の値。結果の文字列が buf_size の制限により切り詰められた場合、この関数は制限が課されなかった場合に書き込まれたであろう総文字数（終端ナルバイトを含まない）を返します。
5,6) 出力ストリームに送信された文字数、または出力エラー、実行時制約違反エラー、エンコーディングエラーが発生した場合は負の値。
7) buffer に書き込まれた文字数（null文字は含まない。ただし buffer がnullポインタでなく、 bufsz がゼロでなく RSIZE_MAX 以下である限り常に書き込まれる）、または実行時制約違反の場合はゼロ、エンコーディングエラーの場合は負の値
8) 終端ナル文字を含まない文字数（ buffer がナルポインタでなく、 bufsz がゼロでなく RSIZE_MAX を超えない限り、常に書き込まれる）、これは bufsz が無視された場合に buffer に書き込まれたであろう文字数、または実行時制約違反もしくはエンコーディングエラーが発生した場合は負の値

注記

これらの関数はすべて少なくとも1回 va_arg を呼び出し、戻り値の後では arg の値は不定となります。これらの関数は va_end を呼び出さないため、呼び出し元が実行する必要があります。

vsnprintf_s は、 vsprintf_s とは異なり、結果を buffer が指す配列内に収まるように切り詰めます。

vsnprintf_s の実装は、 Microsoft CRT においてC標準に準拠していません。Microsoftのバージョンには3番目の位置に追加のパラメータ size_t count があり、これはnull終端文字を含まない書き込み可能な最大文字数を示します。このパラメータは、 size_t bufsz パラメータで指定されるバッファサイズとは異なる可能性があります。

例

このコードを実行 
#include <stdarg.h>
#include <stdio.h>
#include <time.h>
void debug_log(const char* fmt, ...)
{
    struct timespec ts;
    timespec_get(&ts, TIME_UTC);
    char time_buf[100];
    size_t rc = strftime(time_buf, sizeof time_buf, "%D %T", gmtime(&ts.tv_sec));
    snprintf(time_buf + rc, sizeof time_buf - rc, ".%06ld UTC", ts.tv_nsec / 1000);
    va_list args1;
    va_start(args1, fmt);
    va_list args2;
    va_copy(args2, args1);
    char buf[1+vsnprintf(NULL, 0, fmt, args1)];
    va_end(args1);
    vsnprintf(buf, sizeof buf, fmt, args2);
    va_end(args2);
    printf("%s [debug]: %s\n", time_buf, buf);
}
int main(void)
{
    debug_log("Logging, %d, %d, %d", 1, 2, 3);
}

出力例: 

02/20/15 21:58:09.072683 UTC [debug]: Logging, 1, 2, 3

参考文献

  • C23規格 (ISO/IEC 9899:2024):
  • 7.21.6.8 vfprintf関数 (p: 未定)
  • 7.21.6.10 vprintf関数 (p: 未定)
  • 7.21.6.12 vsnprintf関数 (p: 未定)
  • 7.21.6.13 vsprintf関数 (p: 未定)
  • K.3.5.3.8 vfprintf_s関数 (p: 未定)
  • K.3.5.3.10 vprintf_s関数 (p: 未定)
  • K.3.5.3.12 vsnprintf_s関数 (p: 未定)
  • K.3.5.3.13 vsprintf_s関数 (p: 未定)
  • C17規格 (ISO/IEC 9899:2018):
  • 7.21.6.8 vfprintf関数 (p: 238)
  • 7.21.6.10 vprintf関数 (p: 239)
  • 7.21.6.12 vsnprintf関数 (p: 239-240)
  • 7.21.6.13 vsprintf関数 (p: 240)
  • K.3.5.3.8 vfprintf_s関数 (p: 434)
  • K.3.5.3.10 vprintf_s関数 (p: 435)
  • K.3.5.3.12 vsnprintf_s関数 (p: 436-437)
  • K.3.5.3.13 vsprintf_s関数 (p: 437)
  • C11規格 (ISO/IEC 9899:2011):
  • 7.21.6.8 vfprintf関数 (p: 326-327)
  • 7.21.6.10 vprintf関数 (p: 328)
  • 7.21.6.12 vsnprintf関数 (p: 329)
  • 7.21.6.13 vsprintf関数 (p: 329)
  • K.3.5.3.8 vfprintf_s関数 (p: 597)
  • K.3.5.3.10 vprintf_s関数 (p: 598-599)
  • K.3.5.3.12 vsnprintf_s関数 (p: 600)
  • K.3.5.3.13 vsprintf_s関数 (p: 601)
  • C99規格 (ISO/IEC 9899:1999):
  • 7.19.6.8 vfprintf関数 (p: 292)
  • 7.19.6.10 vprintf関数 (p: 293)
  • 7.19.6.12 vsnprintf関数 (p: 294)
  • 7.19.6.13 vsprintf関数 (p: 295)
  • C89/C90標準 (ISO/IEC 9899:1990):
  • 4.9.6.7 vfprintf関数
  • 4.9.6.8 vprintf関数
  • 4.9.6.9 vsprintf関数

関連項目

(C95) (C95) (C95) (C11) (C11) (C11) (C11)
可変長引数リストを使用して書式化されたワイド文字出力を stdout 、ファイルストリーム
またはバッファに出力する
(関数)
(C99) (C11) (C11) (C11) (C11)
書式化された出力を stdout 、ファイルストリームまたはバッファに出力する
(関数)
(C99) (C99) (C99) (C11) (C11) (C11)
可変長引数リストを使用して stdin 、ファイルストリームまたはバッファから
書式化された入力を読み込む
(関数)
C++ documentation for vprintf , vfprintf , vsprintf , vsnprintf