vswprintf | Programming Place Plus　Ｃ言語編　標準ライブラリのリファレンス

概要

変換指定に沿って変換されたワイド文字列を格納する。

ヘッダ

stdio.h、wchar.h

形式

int vswprintf(wchar_t* restrict s, size_t n, const wchar_t* restrict format, va_list args);

引数

s

結果を格納する配列を指すポインタ。

n

終端に書き込まれる L’\0’ を含めた、格納する最大文字数。あるいは 0。

format

変換指定を含んだ、あるいは含まないプレーンな文字列。

args

format に含まれている変換指定子に対応した、可変個引数リスト。

戻り値

実際に書き込まれた文字数（末尾のヌル文字を除く）を返す。エラーが発生した場合は、負数を返す。
引数 n 以上の文字数の書き込みが必要であった場合にも負数を返す。

詳細

仮引数が … から va_list に変わったことを除き、swprintf関数と同等である。変換指定を行い生成されたワイド文字列のうち、引数n で指定した文字数 - 1 文字までが格納され、末尾に L’\0’ が付加される。
関数名からして、マルチバイト文字列を扱う vsprintf関数と対応していそうだが、引数 n が加わっており、安全性が増している。vsnprintf関数と似ているようでもあるが、引数 n の意味するところが違う。vsnprintf関数と違って、変換後の文字列の長さが、格納先の配列の大きさを超えているときには、バッファオーバーフローを起こすことなく失敗する。

注意

第４引数に渡す va_list型のオブジェクトは、事前に va_start による初期化が必要である。

va_list に、必要な個数の引数が含まれていない場合の動作は未定義。余分に存在している場合には、評価は行われるが、vsprintf関数としては無視する。

引数n に指定する値は文字数であって、大きさではないので、sizeof を使って計算する場合には注意が必要である。

使用例

#include <stdio.h>
#include <stdarg.h>
#include <wchar.h>

static void warning(wchar_t* buf, size_t size, const wchar_t* str, ...);

int main(void)
{
    wchar_t buf[256] = L"";
    int value = 100;

    if (value != 0) {
        warning(buf, sizeof(buf) / sizeof(wchar_t), L"value: %d\n", value);
    }

    wprintf(L"%ls\n", buf);
}

void warning(wchar_t* buf, size_t size, const wchar_t* str, ...)
{
    va_list args;

    va_start(args, str);

    swprintf(buf, size, L"[WARNING] ");
    vswprintf(buf, size, str, args);

    va_end(args);
}

実行結果：

value: 100

関連

マルチバイト文字版は vsprintf関数であるが、引数 n に相当するものがない。
va_list の代わりに、… を用いたバージョンとして、swprintf関数がある。

解説章