vsnprintf_s、_vsnprintf_s、_vsnprintf_s_l、_vsnwprintf_s、_vsnwprintf_s_l

[アーティクル]
02/21/2013

引数リストへのポインターを使用して、書式付き出力を書き込みます。これらの関数は、「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
使用するロケール。

詳細については、「scanf 関数と wscanf 関数の書式指定フィールド」を参照してください。

戻り値

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	戻り値	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!!");
}

vsnprintf_s、_vsnprintf_s、_vsnprintf_s_l、_vsnwprintf_s、_vsnwprintf_s_l

パラメーター

戻り値

解説

同等の .NET Framework 関数

必要条件

使用例

参照

関連項目

その他のリソース