vsnprintf_s、_vsnprintf_s、_vsnprintf_s_l、_vsnwprintf_s、_vsnwprintf_s_lvsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l

引数リストへのポインターを使用して、書式付き出力を書き込みます。Write formatted output using a pointer to a list of arguments. これらは、「CRT のセキュリティ機能」の説明にあるとおり、セキュリティが強化されたバージョンの vsnprintf、_vsnprintf、_vsnprintf_l、_vsnwprintf、_vsnwprintf_l です。These are versions of vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l with security enhancements as described in Security Features in the CRT.

構文Syntax

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

パラメーターParameters

バッファーbuffer
出力の格納位置。Storage location for output.

sizeOfBuffersizeOfBuffer
サイズ、バッファー出力の文字数。The size of the buffer for output, as the character count.

countcount
書き込む最大文字数 (終端の null は含まない)、または _TRUNCATEMaximum number of characters to write (not including the terminating null), or _TRUNCATE.

formatformat
書式の指定。Format specification.

argptrargptr
引数リストへのポインター。Pointer to list of arguments.

localelocale
使用するロケール。The locale to use.

詳細については、「 printf 関数と wprintf 関数の書式指定フィールド」を参照してください。For more information, see Format Specifications.

戻り値Return Value

vsnprintf_s_vsnprintf_s_vsnwprintf_s出力エラーが発生した場合に、終端の null または負の値をしないなど、書き込まれる文字数を返します。vsnprintf_s, _vsnprintf_s and _vsnwprintf_s return the number of characters written, not including the terminating null, or a negative value if an output error occurs. vsnprintf_sヲェヒェケェ ・ _vsnprintf_sします。vsnprintf_s is identical to _vsnprintf_s. vsnprintf_sは ANSI 規格に準拠する目的で含まれます。vsnprintf_s is included for compliance to the ANSI standard. _vnsprintf旧バージョンとの互換性は保持されます。_vnsprintf is retained for backward compatibility.

データと終端の null の格納に必要なストレージを超える場合sizeOfBufferで説明されているとおり、無効なパラメーター ハンドラーが呼び出されますパラメーターの検証がない限り、_TRUNCATE、場合の文字列と同様に収まるバッファーが書き込まれると、-1 が返されます。If the storage required to store the data and a terminating null exceeds sizeOfBuffer, the invalid parameter handler is invoked, as described in Parameter Validation, unless count is _TRUNCATE, in which case as much of the string as will fit in buffer is written and -1 returned. これらの関数の設定は無効パラメーター ハンドラーの後に実行が引き続き発生する場合バッファー空の文字列に次のように設定します。 errnoERANGE、-1 を返します。If execution continues after the invalid parameter handler, these functions set buffer to an empty string, set errno to ERANGE, and return -1.

場合バッファーまたは形式は、 NULLポインター、またはカウントと同じかそれよりも少ない対 0 の場合、無効なパラメーター ハンドラーが呼び出されます。If buffer or format is a NULL pointer, or if count is less than or equal to zero, the invalid parameter handler is invoked. 実行の継続が許可された場合に、これらの関数が設定errnoEINVALし、-1 を返します。If execution is allowed to continue, these functions set errno to EINVAL and return -1.

エラー条件Error Conditions

条件Condition ReturnReturn errnoerrno
バッファーNULLbuffer is NULL -1-1 EINVALEINVAL
形式NULLformat is NULL -1-1 EINVALEINVAL
カウント< = 0count <= 0 -1-1 EINVALEINVAL
sizeOfBuffer小さすぎる (とカウント! = _TRUNCATE)sizeOfBuffer too small (and count != _TRUNCATE) -1 (とバッファー空の文字列に設定)-1 (and buffer set to an empty string) ERANGEERANGE

RemarksRemarks

これらの各関数、引数リストへのポインターを受け取る書式設定して最大書き込みますカウントによって示されるメモリに指定されたデータの文字バッファー終端の null を追加します。Each of these functions takes a pointer to an argument list, then formats and writes up to count characters of the given data to the memory pointed to by buffer and appends a terminating null.

場合カウント_TRUNCATE、これらの関数の多くに収まる限りの文字列として書き込みバッファー終端の null 用の空きを残して中にします。If count is _TRUNCATE, then these functions write as much of the string as will fit in buffer while leaving room for a terminating null. 文字列全体 (終端の null) が内に収まるかどうかバッファー、し、これらの関数は、(終端の null は含まない) に書き込まれた文字数を返しますそれ以外の場合、これらの関数がその切り捨ては-1 を返します。発生しました。If the entire string (with terminating null) fits in buffer, then these functions return the number of characters written (not including the terminating null); otherwise, these functions return -1 to indicate that truncation occurred.

これらの関数のバージョン、 _l現在のスレッド ロケールの代わりに渡されたロケール パラメーターを使用する点を除いて、サフィックスは同じです。The versions of these functions with the _l suffix are identical except that they use the locale parameter passed in instead of the current thread locale.

重要

format にユーザー定義の文字列を指定しないでください。Ensure that format is not a user-defined string. 詳しくは、「 バッファー オーバーランの回避」をご覧ください。For more information, see Avoiding Buffer Overruns.

注意

終端の null 用の空きがあることを確認するには、必ずカウントは、バッファーの長さ、またはより厳密に小さい _TRUNCATEします。To ensure that there is room for the terminating null, be sure that count is strictly less than the buffer length, or use _TRUNCATE.

C++ では、これらの関数の使用はテンプレートのオーバーロードによって簡素化されます。オーバーロードでは、バッファー長を自動的に推論できる (サイズの引数を指定する必要がなくなる) だけでなく、古くてセキュリティが万全ではない関数を新しく安全な関数に自動的に置き換えることができます。In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. 詳細については、「 Secure Template Overloads」を参照してください。For more information, see Secure Template Overloads.

汎用テキスト ルーチンのマップGeneric-Text Routine Mappings

TCHAR.H のルーチンTCHAR.H routine _UNICODE および _MBCS が未定義の場合_UNICODE & _MBCS not defined _MBCS が定義されている場合_MBCS defined _UNICODE が定義されている場合_UNICODE defined
_vsntprintf_s_vsntprintf_s _vsnprintf_s_vsnprintf_s _vsnprintf_s_vsnprintf_s _vsnwprintf_s_vsnwprintf_s
_vsntprintf_s_l_vsntprintf_s_l _vsnprintf_s_l_vsnprintf_s_l _vsnprintf_s_l_vsnprintf_s_l _vsnwprintf_s_l_vsnwprintf_s_l

必要条件Requirements

ルーチンによって返される値Routine 必須ヘッダーRequired header 省略可能なヘッダーOptional headers
vsnprintf_svsnprintf_s <stdio.h> および <stdarg.h><stdio.h> and <stdarg.h> <varargs.h>*<varargs.h>*
_vsnprintf_s_vsnprintf_s_l_vsnprintf_s, _vsnprintf_s_l <stdio.h> および <stdarg.h><stdio.h> and <stdarg.h> <varargs.h>*<varargs.h>*
_vsnwprintf_s_vsnwprintf_s_l_vsnwprintf_s, _vsnwprintf_s_l <stdio.h> または <wchar.h>、および <stdarg.h><stdio.h> or <wchar.h>, and <stdarg.h> <varargs.h>*<varargs.h>*

* UNIX V との互換性用。* Required for UNIX V compatibility.

互換性の詳細については、「 互換性」を参照してください。For additional compatibility information, see Compatibility.

Example

// 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, _countof(buff), _TRUNCATE, formatstring, args);
   printf("nSize: %d, buff: %s\n", nSize, buff);
   va_end(args);
}

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!

関連項目See also

ストリーム入出力Stream I/O
vprintf 系関数vprintf Functions
fprintf、_fprintf_l、fwprintf、_fwprintf_lfprintf, _fprintf_l, fwprintf, _fwprintf_l
printf、_printf_l、wprintf、_wprintf_lprintf, _printf_l, wprintf, _wprintf_l
sprintf、_sprintf_l、swprintf、_swprintf_l、__swprintf_lsprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
va_arg、va_copy、va_end、va_startva_arg, va_copy, va_end, va_start