名前空間
変種
操作

vwprintf, vfwprintf, vswprintf, vwprintf_s, vfwprintf_s, vswprintf_s, vsnwprintf_s

提供: cppreference.com
< c‎ | io
 
 
ファイル入出力
関数
ファイルアクセス
直接入出力
書式なし入出力
(C11以前)(C11およびそれ以降)
(C95)(C95)
(C95)
(C95)(C95)
(C95)
(C95)
書式付き入力
書式付き出力
vwprintfvfwprintfvswprintfvwprintf_svfwprintf_svswprintf_svsnwprintf_s
(C95)(C95)(C95)(C11)(C11)(C11)(C11)
ファイル位置操作
エラー処理
ファイルに対する操作
 
ヘッダ <wchar.h> で定義
(1)
int vwprintf( const wchar_t *format, va_list vlist );
(C95およびそれ以降)
(C99以前)
int vwprintf( const wchar_t *restrict format, va_list vlist );
(C99およびそれ以降)
(2)
int vfwprintf( FILE* stream, const wchar_t *format, va_list vlist );
(C95およびそれ以降)
(C99以前)
int vfwprintf( FILE *restrict stream,
               const wchar_t *restrict format, va_list vlist );
(C99およびそれ以降)
(3)
int vswprintf( wchar_t *buffer, size_t bufsz,
               const wchar_t *format, va_list vlist );
(C95およびそれ以降)
(C99以前)
int vswprintf( wchar_t *restrict buffer, size_t bufsz,
               const wchar_t *restrict format, va_list vlist );
(C99およびそれ以降)
int vwprintf_s( const wchar_t *restrict format, va_list vlist);
(4) (C11およびそれ以降)
int vfwprintf_s( FILE * restrict stream,
                 const wchar_t *restrict format, va_list vlist);
(5) (C11およびそれ以降)
int vswprintf_s( wchar_t *restrict buffer, rsize_t bufsz,
                 const wchar_t * restrict format, va_list vlist);
(6) (C11およびそれ以降)
int vsnwprintf_s( wchar_t *restrict buffer, rsize_t bufsz,
                  const wchar_t *restrict format, va_list vlist);
(7) (C11およびそれ以降)

vlist によって定義される位置からデータをロードし、それらをワイド文字列に変換し、結果を様々なシンクに書き込みます。

1) 結果を stdout に書き込みます。
2) 結果をファイルストリーム stream に書き込みます。
3) 結果をワイド文字列 buffer に書き込みます。 最大 bufsz-1 個のワイド文字およびそれに続くヌルワイド文字が書き込まれます。 bufsz がゼロでなければ、結果のワイド文字列はヌルワイド文字で終端されます。
4-6) (1-3) と同じですが、以下のエラーが実行時に検出され、現在設定されている制約ハンドラ関数を呼びます。
  • format に変換指定子 %n が存在する。
  • %s に対応するいずれかの引数がヌルポインタ。
  • format または buffer がヌルポインタ。
  • bufsz がゼロまたは RSIZE_MAX/sizeof(wchar_t) より大きい。
  • いずれかの文字列または文字変換指定子でエンコーディングエラーが発生する。
  • (vswprintf_s の場合のみ) buffer に格納される文字列 (末尾のワイドヌルを含む) が bufsz を超える。
7) (6) と同じですが、 buffer の指す配列に収まるように結果を切り捨てます。
すべての境界チェック付き関数と同様に、 vwprintf_svfwprintf_svswprintf_s および vsnwprintf_s__STDC_LIB_EXT1__ が処理系によって定義されていて、 <wchar.h> をインクルードする前にユーザが __STDC_WANT_LIB_EXT1__ を整数定数 1 に定義した場合にのみ、利用可能であることが保証されます。

目次

[編集] 引数

stream - 書き込む出力ファイルストリーム
buffer - 書き込むワイド文字列を指すポインタ
bufsz - 書き込み最大ワイド文字数
format - データの解釈方法を指定するヌル終端ワイド文字列を指すポインタ。

書式文字列は、変更されずに出力ストリームにコピーされる (% を除く) 通常のワイド文字と、変換指定から構成されます。 各変換指定は以下の書式を持ちます。

  • 最初の % 文字。
  • (オプション) 変換の動作を変更する1つ以上のフラグ。
  • - : 変換の結果をフィールド内で左詰めします。 (デフォルトでは右詰めされます)。
  • + : 符号付き変換の符号が必ず変換の結果の前に付加されます (デフォルトでは負の場合にのみマイナスが結果の前に付加されます)。
  • 空白 : 符号付き変換の結果が符号文字で始まらない、または空の場合、空白が結果の前に付加されます。 + フラグが存在する場合、このフラグは無視されます。
  • # : 変換の代替形式が行われます。 正確な効果は下の表を参照してください。 記載がなければ動作は未定義です。
  • 0 : 整数または浮動小数点数の変換に対して、フィールドをパディングするために空白文字の代わりに先行するゼロが使用されます。 整数の場合、精度が明示的に指定されていれば、このフラグは無視されます。 それ以外の変換に対してこのフラグを使用した結果は未定義動作です。 - フラグが存在する場合、このフラグは無視されます。
  • (オプション) 最小フィールド幅を指定する整数値または *。 結果は、必要の場合は、左詰めの場合は右側に、右詰めの場合は左側に、 (デフォルトでは) 空白文字で、パディングされます。 * が使用された場合、幅は int 型の追加の引数によって指定されます。 引数の値が負の場合は、 - フラグと正のフィールド幅として解釈されます。 (ノート: これは最小の幅です。 値が切り捨てられることはありません。)
  • (オプション) 変換の精度を指定する . に続く整数または *、またはそのいずれも続かない単体の .* が使用された場合、 精度int 型の追加の引数によって指定されます。 この引数の値が負の場合、それは無視されます。 数値も * も続かない単体の . が使用された場合、精度はゼロとして扱われます。 精度 の正確な効果は下の表を参照してください。
  • (オプション) 引数のサイズを指定する長さ修飾子
  • 変換書式指定子。

以下の書式指定子が利用できます。

変換指定子 説明 引数の型
長さ修飾子 hh

(C99)

h なし l ll

(C99)

j

(C99)

z

(C99)

t

(C99)

L
% % を書き込みます。 変換指定全体が %% でなければなりません。 N/A N/A N/A N/A N/A N/A N/A N/A N/A
c

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

引数はまず、 btowc を呼んだかのように、 wchar_t に変換されます。 l 修飾子が使用された場合は、 wint_t 引数がまず wchar_t に変換されます。

N/A N/A
int
wint_t
N/A N/A N/A N/A N/A
s

文字列を書き込みます。

引数は初期シフト状態で始まるマルチバイト文字シーケンスを格納している文字配列の最初の要素を指すポインタでなければなりません。 それは、ゼロ初期化された変換状態を使用して mbrtowc を呼んだかのように、ワイド文字配列に変換されます。 精度は書き込まれる最大ワイド文字数を指定します。 精度が指定されていない場合は、最初のヌル終端に達するまで、すべてのワイド文字が書き込まれます (ヌル終端は書き込まれません)。 l' 修飾子が使用された場合は、引数は wchar_t 配列の最初の要素を指すポインタでなければなりません。

N/A N/A
char*
wchar_t*
N/A N/A N/A N/A N/A
d
i

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

精度は出力される最小桁数を指定します。 デフォルトの精度は 1 です。 変換後の値と精度がどちらも 0 であれば変換結果は空文字列になります。

signed char
short
int
long
long long
signed size_t
N/A
o

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

精度は出力される最小桁数を指定します。 デフォルトの精度は 1 です。 変換後の値と精度がどちらも 0 であれば変換結果は空文字列になります。 代替表現では前にゼロを1個付加するために必要に応じて精度が増えます。 その場合、変換後の値と精度がどちらも 0 であれば単一の 0 が書き込まれます。

unsigned char
unsigned short
unsigned int
unsigned long
unsigned long long
unsigned version of ptrdiff_t
N/A
x
X

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

x 変換の場合は文字 abcdef が使用されます。 X 変換の場合は文字 ABCDEF が使用されます。

精度は出力される最小桁数を指定します。 デフォルトの精度は 1 です。 変換後の値と精度がどちらも 0 であれば変換結果は空文字列になります。 代替表現では変換結果がゼロでなければ結果の前に 0x または 0X が付加されます。

N/A
u

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

精度は出力される最小桁数を指定します。 デフォルトの精度は 1 です。 変換後の値と精度がどちらも 0 であれば変換結果は空文字列になります。

N/A
f
F

浮動小数点数[-]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.ddde±dd 形式が使用されます。 E 変換の場合は [-]d.dddE±dd 形式が使用されます。

指数は少なくとも2桁あり、必要に応じて桁数が増えます。 値が 0 であれば、指数も 0 になります。 精度は小数点以下の最小桁数を指定します。 デフォルトの精度は 6 です。 代替表現では小数点の後に何もなくても小数点文字が書き込まれます。 無限大および非数の変換形式についてはノートを参照してください。

N/A N/A N/A N/A N/A N/A
a
A

(C99)

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

a 変換の場合は [-]0xh.hhhp±d 形式が使用されます。 A 変換の場合は [-]0Xh.hhhP±d 形式が使用されます。

引数が正規化浮動小数点数の場合、最初の16進数桁は 0 になりません。 値が 0 であれば、指数も 0 になります。 精度は小数点以下の最小桁数を指定します。 デフォルトの精度は値を正確に表現するのに十分な値です。 代替表現では小数点の後に何もなくても小数点文字が書き込まれます。 無限大および非数の変換形式についてはノートを参照してください。

N/A N/A N/A N/A N/A N/A
g
G

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

g 変換の場合は e または f 形式の変換が行われます。 G 変換の場合は E または F 形式の変換が行われます。

P を非ゼロの場合は精度と等しい値、精度が指定されていない場合は 6、精度が 0 の場合は 1 と置いたとき、 E 形式の変換で指数が X である場合、

  • P > X ≥ −4 であれば、変換は f または F の形式と P − 1 − X の精度を持ちます。
  • そうでなければ、変換は e または E の形式と P − 1 の精度を持ちます。

代替表現が要求されなければ、末尾のゼロは削除され、小数点以下が残っていなければ、小数点文字も削除されます。 無限大および非数の変換形式についてはノートを参照してください。

N/A N/A N/A N/A N/A N/A
n

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

結果は引数の指している値に書き込まれます。 仕様はフラグフィールド幅精度のいずれも含んでいてはいけません。

signed char*
short*
int*
long*
long long*
signed size_t*
N/A
p

ポインタを定義する処理系定義の文字シーケンスを書き込みます。

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 を出力します。

%cint 引数を期待しますが、可変長引数関数が呼ばれるときに行われる整数昇格のため、 char を渡しても安全です。

固定幅の整数型 (int8_t など) に対する正しい変換指定はヘッダ <inttypes.h> で定義されています (PRIdMAX, PRIuMAX などは %jd, %ju などの同義語ですが)。

メモリに書き込む変換指定子 %n は、書式文字列がユーザ入力に依存する場合、セキュリティエクスプロイトのよくあるターゲットであり、境界チェック付きの printf_s ファミリーの関数ではサポートされていません。

変換指定子それぞれの動作後に副作用完了点があります。 これにより同じ変数に複数の %n の結果を格納することができ、またエッジケースとして、同じ呼び出しの中で先行する %n によって変更された値を表示することができます。

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


vlist - 表示するデータを格納している可変長引数リスト

[編集] 戻り値

1-3) 成功した場合は書き込まれたワイド文字数、エラーが発生した場合は負の値。
4) 成功した場合は書き込まれたワイド文字数、エラーが発生した場合は負の値。 結果の文字列が bufsz の制限のために切り捨てられた場合は、制限が課されなければ書き込まれたであろう合計文字数 (終端のヌルワイド文字は含みません) を返します。
5,6) 出力ストリームに転送されたワイド文字数、または出力エラー、実行時制約違反エラー、またはエンコーディングエラーが発生した場合は負の値。
7) buffer に書き込まれたヌルワイド文字を含まないワイド文字数 (buffer がヌルポインタでなく、 bufsz がゼロでなく RSIZE_MAX/sizeof(wchar_t) より大きくなければ、ヌルワイド文字はは必ず書き込まれます)、実行時制約違反の場合はゼロ、エンコーディングエラーの場合は負の値。
8) bufsz が無視されたならば buffer に書き込まれたであろう終端のヌル文字を含まないワイド文字数 (buffer がヌルポインタでなく、 bufsz がゼロでなく RSIZE_MAX/sizeof(wchar_t) より大きくなければ、終端のヌル文字は必ず書き込まれます)、実行時制約違反の場合またはエンコーディングエラーが発生した場合は負の値。

[編集] ノート

これらのすべての関数は va_arg を少なくとも1回は呼び、戻った後 arg の値は不定になります。 これらの関数は va_end を呼ばす、それは呼び出し元が行わなければなりません。

ナロー文字列が要求される出力バッファサイズを調べられる vsnprintf を提供する一方、 (C11 の vsnwprintf_s までは) ワイド文字列に対する同等な関数はありませんでした。 バッファサイズを決定するためには、 vswprintf を呼び、結果の値をチェックし、より大きなバッファを確保し直し、成功するまで同様に試みる必要がありました。

vsnwprintf_s は、 vswprintf_s と異なり、ほとんどの境界チェック付き関数が切り捨てをエラーとして扱うところ、 buffer の指す配列内に収まるよう結果を切り捨てます。

[編集]

#include <stdio.h>
#include <time.h>
#include <locale.h>
 
void debug_wlog(const wchar_t *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 args;
    va_start(args, fmt);
    wchar_t buf[1000];
    int rc2 = vswprintf(buf, sizeof buf / sizeof *buf, fmt, args);
    va_end(args);
 
    if(rc2 > 0)
       wprintf(L"%s [debug]: %ls\n", time_buf, buf);
    else
       wprintf(L"%s [debug]: (string too long)\n", time_buf);
}
 
int main(void)
{
    setlocale(LC_ALL, "");
    debug_wlog(L"Logging, %d, %d, %d", 1, 2, 3);
}

出力例:

02/20/15 22:12:38.476575 UTC [debug]: Logging, 1, 2, 3

[編集] 参考文献

  • C11 standard (ISO/IEC 9899:2011):
  • 7.29.2.5 The vfwprintf function (p: 417-418)
  • 7.29.2.7 The vswprintf function (p: 419)
  • 7.29.2.9 The vwprintf function (p: 420)
  • K.3.9.1.6 The vfwprintf_s function (p: 632)
  • K.3.9.1.8 The vsnwprintf_s function (p: 633-634)
  • K.3.9.1.9 The vswprintf_s function (p: 634-635)
  • K.3.9.1.11 The vwprintf_s function (p: 636)
  • C99 standard (ISO/IEC 9899:1999):
  • 7.24.2.5 The vfwprintf function (p: 363)
  • 7.24.2.7 The vswprintf function (p: 364)
  • 7.24.2.9 The vwprintf function (p: 365)

[編集] 関連項目

stdout、ファイルストリームまたはバッファに可変個引数リストを使用して書式付き出力を書き出します
(関数) [edit]
stdout、ファイルストリームまたはバッファに書式付きワイド文字出力を書き出します
(関数) [edit]
vwprintf, vfwprintf, vswprintfC++リファレンス