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

トップページ – Ｃ言語編 – 標準ライブラリのリファレンス（名前順）

トップページ – Ｃ言語編 – 標準ライブラリのリファレンス（ヘッダ別）

vsnprintf関数

概要 変換指定に沿って変換された文字列を、指定文字数以下だけ格納する。
ヘッダ stdio.h
形式 int vsnprintf(char* restrict s, size_t n, const char* restrict format, va_list args);
引数 s

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

引数n が 0 の場合に限って、ヌルポインタでも構わない。
n

s に書き込む最大文字数。終端に書き込まれる ‘\0’ を含めた文字数である。

0 を指定することはできるが、この場合は何も書き込まれない。
format 変換指定を含んだ、あるいは含まないプレーンな文字列。
args format に含まれている変換指定子に対応した、可変個引数リスト。
戻り値

実際に書き込まれたはずの文字数（末尾のヌル文字は除く）を返す。つまり、変換指定を行った結果の文字列の長さが、引数n の値以上になった場合、引数n による制限によって書き込まれなかった部分の長さも含めて返される。

変換に関するエラーが発生した場合は、負数を返す。
詳細

書き込む最大文字数を指定することを除いて、vsprintf関数と同じ機能を持つ。最大文字数を指定できることで、バッファオーバーフローを防止できるが、完全に防ぐためには、使い方に若干の注意を要する（「注意」のところで解説する）。

機能としては、仮引数が … から va_list に変わったことを除き、snprintf関数と同等である。
注意

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

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

この関数は内部で va_argマクロを呼び出すため、関数から戻った後の args の状態は不定である。

バッファオーバーフローの備えがない vsprintf関数と比べると、この関数は安全性が増しているが、その安全性を得るために、引数n に、引数s が示す配列の実際の要素数（あるいはそれ以下の値）を指定するように注意しなければならない。引数n が実際の要素数より大きく、かつ、%d などを変換したあとの文字列の長さが、書き込み先の配列の要素数よりも長くなる場合には、バッファオーバーフローは起こる。安全のためには、sizeof を使うなどして、配列の要素数を確実に渡す（たとえば、vsnprintf(s, sizeof(s), "%d", args); のように）。ただし、s が動的メモリ割り当てで確保された配列を指すポインタになっている場合など、sizeof(s) とはできないケースに注意すること。
使用例 
#include <stdio.h>
#include <stdarg.h>

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

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

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

    puts(buf);
}

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

    va_start(args, str);

    buf += sprintf(buf, "[WARNING] ");
    vsnprintf(buf, size, str, args);

    va_end(args);
}

実行結果：

[WARNING] value: 100
関連

この関数のワイド文字版は直接的に対応するものはないが、vswprintf関数 が近い。戻り値の意味などに違いがあることに注意。vsnwprintf のような名前の標準関数はない。


va_list の代わりに、… を用いたバージョンとして、snprintf関数がある。
解説章


参考リンク 🔗

本ページはアフィリエイトプログラムによる収益を得ています。
以下のリンクから商品を購入されると、Programming Place 管理者に紹介料が支払われています。


更新履歴 🔗

　「NULL」という表記を「ヌルポインタ」に修正。

　全体的に文章を見直し修正。
「詳細」「注意」を加筆。

　Ｃ言語編全体で表記を統一するため、「フォーマット指定」を「変換指定」に改めた。

　新規作成。


標準ライブラリのリファレンス（名前順）のトップページへ

標準ライブラリのリファレンス（ヘッダ別）のトップページへ

Ｃ言語編のトップページへ

Programming Place Plus のトップページへ

はてなブックマーク に保存 Pocket に保存 Facebook でシェア
X で ポスト／フォロー LINE で送る noteで書く
rss1.0 取得ボタン RSS 管理者情報 プライバシーポリシー
先頭へ戻る