vsnprintf_s、_vsnprintf_s、_vsnprintf_s_l、_vsnwprintf_s、_vsnwprintf_s_l

[アーティクル]
09/17/2008

更新 : 2007 年 11 月

引数リストへのポインタを使用して、書式付き出力を書き込みます。これらの関数は、「CRT のセキュリティ強化」に説明されているように、vsnprintf、_vsnprintf、_vsnprintf_l、_vsnwprintf、_vsnwprintf_l のセキュリティが強化されたバージョンです。

int vsnprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   va_list argptr 
);
int _vsnprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   va_list argptr 
);
int _vsnprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   locale_t locale,
   va_list argptr 
);
int _vsnwprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format,
   va_list argptr 
);
int _vsnwprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format,
   locale_t locale,
   va_list argptr 
);
template <size_t size>
int _vsnprintf_s(
   char (&buffer)[size],
   size_t count,
   const char *format,
   va_list argptr 
); // C++ only
template <size_t size>
int _vsnwprintf_s(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   va_list argptr 
); // C++ only

パラメータ

buffer
出力の格納位置。
sizeOfBuffer
出力の buffer のサイズ。
count
書き込む最大文字数 (終端の null は含まない)、または _TRUNCATE。
format
書式の指定。
argptr
引数リストへのポインタ。
locale
使用するロケール。

戻り値

vsnprintf_s、_vsnprintf_s 、および_vsnwprintf_s 関数は書き込まれた文字数を返します。終端の null は含まれません。出力エラーが発生した場合は、負の値を返します。vsnprintf_s 関数は _vsnprintf_s 関数と同じです。vsnprintf_s 関数は ANSI 規格に準拠する目的で含まれています。_vnsprintf は下位互換性を保つ目的で保持されています。

データと終端の null の格納に必要なストレージが sizeOfBuffer を超える場合は、「パラメータの検証」に説明されているように、無効なパラメータハンドラが呼び出されます。ただし、count が _TRUNCATE の場合は、buffer に収まる限りの文字列が書き込まれ、-1 が返されます。無効なパラメータハンドラの後に実行が継続されると、これらの関数は buffer を空の文字列に、errno を ERANGE に設定し、-1 を返します。

buffer または format が NULL ポインタの場合、またはcount が 0 以下の場合は、無効なパラメータハンドラが呼び出されます。実行の継続が許可された場合、これらの関数は errno を EINVAL に設定し、-1 を返します。

エラー条件

Condition	Return	errno
buffer が NULL	-1	EINVAL
format が NULL	-1	EINVAL
count <= 0	-1	EINVAL
sizeOfBuffer が小さすぎる (および count != _TRUNCATE)	-1 (および buffer が空の文字列に設定される)	ERANGE

解説

これらの関数は、引数リストへのポインタを使用し、指定されたデータを書式指定して count の文字数まで buffer が指すメモリに書き込み、終端の null を追加します。

count が _TRUNCATE の場合、これらの関数は終端の null 用の空きを残して buffer に収まる限りの文字列を書き込みます。文字列全体 (終端の null を含む) が buffer 内に収まる場合は、これらの関数は書き込まれた文字数を返します (終端の null は含まない)。それ以外の場合には -1 を返し、切り捨てが行われたことを示します。

_l サフィックスが付いているこれらの関数の各バージョンは、現在のスレッドロケールの代わりに渡されたロケールパラメータを使用する点を除いて同じです。

セキュリティに関するメモ :
format にユーザー定義の文字列を指定しないでください。詳細については、「Avoiding Buffer Overruns」を参照してください。

メモ :
終端の null 用の空きを確保するために、count を必ずバッファ長未満にするか、_TRUNCATE を使用します。

C++ では、これらの関数の使用はテンプレートのオーバーロードによって簡素化されます。オーバーロードでは、バッファ長を自動的に推論できる (サイズの引数を指定する必要がなくなる) だけでなく、古くてセキュリティが万全ではない関数を新しく安全な関数に自動的に置き換えることができます。詳細については、「セキュリティ保護されたテンプレートオーバーロード」を参照してください。

汎用テキストルーチンのマップ

TCHAR.H のルーチン	_UNICODE および _MBCS が未定義の場合	_MBCS が定義されている場合	_UNICODE が定義されている場合
_vsntprintf_s	_vsnprintf_s	_vsnprintf_s	_vsnwprintf_s
_vsntprintf_s_l	_vsnprintf_s_l	_vsnprintf_s_l	_vsnwprintf_s_l

.NET Framework の相当するアイテム

適用できません。標準 C 関数を呼び出すには、PInvoke を使用します。詳細については、「プラットフォーム呼び出しの例」を参照してください。

必要条件

ルーチン	必須ヘッダー	省略可能なヘッダー
vsnprintf_s	<stdio.h> および <stdarg.h>	<varargs.h>*
_vsnprintf_s, _vsnprintf_s_l	<stdio.h> および <stdarg.h>	<varargs.h>*
_vsnwprintf_s, _vsnwprintf_s_l	<stdio.h> または <wchar.h>、および <stdarg.h>	<varargs.h>*

* UNIX V との互換性用

互換性の詳細については、「C ランタイムライブラリ」の「互換性」を参照してください。

使用例

// crt_vsnprintf_s.cpp
#include <stdio.h>
#include <wtypes.h>

void FormatOutput(LPCSTR formatstring, ...) 
{
   int nSize = 0;
   char buff[10];
   memset(buff, 0, sizeof(buff));
   va_list args;
   va_start(args, formatstring);
   nSize = vsnprintf_s( buff, sizeof(buff), _TRUNCATE, formatstring, args);
   printf("nSize: %d, buff: %s\n", nSize, buff);
}

int main() {
   FormatOutput("%s %s", "Hi", "there");
   FormatOutput("%s %s", "Hi", "there!");
   FormatOutput("%s %s", "Hi", "there!!");
}

nSize: 8, buff: Hi there
nSize: 9, buff: Hi there!
nSize: -1, buff: Hi there!