vsnprintf、_vsnprintf、_vsnprintf_l、_vsnwprintf、_vsnwprintf_lvsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l

引数リストへのポインターを使用して、書式付き出力を書き込みます。Write formatted output using a pointer to a list of arguments. これらの関数のセキュリティを強化したバージョンを使用できます。「 vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l」をご覧ください。More secure versions of these functions are available; see vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l.

構文Syntax

int vsnprintf(
   char *buffer,
   size_t count,
   const char *format,
   va_list argptr
);
int _vsnprintf(
   char *buffer,
   size_t count,
   const char *format,
   va_list argptr
);
int _vsnprintf_l(
   char *buffer,
   size_t count,
   const char *format,
   locale_t locale,
   va_list argptr
);
int _vsnwprintf(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format,
   va_list argptr
);
int _vsnwprintf_l(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format,
   locale_t locale,
   va_list argptr
);
template <size_t size>
int vsnprintf(
   char (&buffer)[size],
   size_t count,
   const char *format,
   va_list argptr
); // C++ only
template <size_t size>
int _vsnprintf(
   char (&buffer)[size],
   size_t count,
   const char *format,
   va_list argptr
); // C++ only
template <size_t size>
int _vsnprintf_l(
   char (&buffer)[size],
   size_t count,
   const char *format,
   locale_t locale,
   va_list argptr
); // C++ only
template <size_t size>
int _vsnwprintf(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   va_list argptr
); // C++ only
template <size_t size>
int _vsnwprintf_l(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   locale_t locale,
   va_list argptr
); // C++ only

パラメーターParameters

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

countcount
書き込む最大文字数。Maximum number of characters to write.

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関数は、書き込まれた文字数を返します。終端の null 文字はカウントされません。The vsnprintf function returns the number of characters written, not counting the terminating null character. Countで指定されたバッファーサイズが、 formatおよびargptrによって指定された出力を格納するのに十分な大きさではない場合、 vsnprintfの戻り値は、書き込まれる文字数になります。これは、 countが十分に大きい場合、null 文字をカウントしません。If the buffer size specified by count is not sufficiently large to contain the output specified by format and argptr, the return value of vsnprintf is the number of characters that would be written, not counting the null character, if count were sufficiently large. 戻り値がcount -1 より大きい場合、出力は切り捨てられます。If the return value is greater than count - 1, the output has been truncated. 戻り値 -1 は、エンコード エラーが発生したことを示します。A return value of -1 indicates that an encoding error has occurred.

_Vsnprintf関数と _vsnwprintf関数は、書き込み対象の文字数がcount以下の場合に書き込まれた文字数を返します。書き込む文字数がcountよりも大きい場合、これらの関数は、出力が切り捨てられたことを示す-1 を返します。Both _vsnprintf and _vsnwprintf functions return the number of characters written if the number of characters to write is less than or equal to count; if the number of characters to write is greater than count, these functions return -1 indicating that output has been truncated.

これらすべての関数によって返される値には、書き込まれているかどうかを問わず、終端の null は含まれません。The value returned by all these functions does not include the terminating null, whether one is written or not. Countが0の場合、返される値は、関数が書き込む文字の数です。終端の null は含まれません。When count is zero, the value returned is the number of characters the functions would write, not including any terminating null. この結果を用いて文字列と終端の null に対して十分なバッファー領域を割り当て、関数を再び呼び出してバッファーを埋めることができます。You can use this result to allocate sufficient buffer space for the string and its terminating null, and then call the function again to fill the buffer.

Formatnullの場合、またはbuffernullで、 countが0以外の場合、「パラメーターの検証」で説明されているように、これらの関数は無効なパラメーターハンドラーを呼び出します。If format is NULL, or if buffer is NULL and count is not equal to zero, these functions invoke the invalid parameter handler, as described in Parameter Validation. 実行の継続が許可された場合、これらの関数は-1 を返し、 errnoEINVALに設定します。If execution is allowed to continue, these functions return -1 and set errno to EINVAL.

RemarksRemarks

これらの各関数は、引数リストへのポインターを受け取り、データを書式設定して、バッファーが指すメモリに最大文字を書き込みます。Each of these functions takes a pointer to an argument list, then formats the data, and writes up to count characters to the memory pointed to by buffer. Vsnprintf関数は、出力を切り捨てる場合でも、常に null 終端文字を書き込みます。The vsnprintf function always writes a null terminator, even if it truncates the output. _Vsnprintf_vsnwprintfを使用する場合、バッファーは、末尾に余裕がある場合 (つまり、書き込む文字数がカウント未満の場合) にのみ null で終了します。When using _vsnprintf and _vsnwprintf, the buffer will be null-terminated only if there is room at the end (that is, if the number of characters to write is less than count).

重要

特定の種類のセキュリティリスクを回避するには、その形式がユーザー定義の文字列ではないことを確認します。To prevent certain kinds of security risks, ensure that format is not a user-defined string. 詳しくは、「 バッファー オーバーランの回避」をご覧ください。For more information, see Avoiding Buffer Overruns.

注意

_Vsnprintf_vsnprintf_l_vsnwprintfおよび _vsnwprintf_lを呼び出すときに、終端の null 用の空き領域があることを確認するには、 countがバッファーの長さより厳密に小さく、バッファーを null に初期化してから、関数を呼び出します。To ensure that there is room for the terminating null when calling _vsnprintf, _vsnprintf_l, _vsnwprintf and _vsnwprintf_l, be sure that count is strictly less than the buffer length and initialize the buffer to null prior to calling the function.

Vsnprintfは常に終端の null を書き込むため、 countパラメーターはバッファーのサイズと同じにすることができます。Because vsnprintf always writes the terminating null, the count parameter may be equal to the size of the buffer.

Visual Studio 2015 と Windows 10 の UCRT 以降、 vsnprintf_vsnprintfと同じではなくなりました。Beginning with the UCRT in Visual Studio 2015 and Windows 10, vsnprintf is no longer identical to _vsnprintf. Vsnprintf関数は、C99 標準に準拠しています。 _vnsprintfは、旧バージョンの Visual Studio code との下位互換性のために残されています。The vsnprintf function complies with the C99 standard; _vnsprintf is retained for backward compatibility with older Visual Studio code.

_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.

C++ では、これらの関数にテンプレートのオーバーロードがあります。このオーバーロードは、これらの関数に対応するセキュリティで保護された新しい関数を呼び出します。In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. 詳細については、「セキュリティ保護されたテンプレート オーバーロード」を参照してください。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_vsntprintf _vsnprintf_vsnprintf _vsnprintf_vsnprintf _vsnwprintf_vsnwprintf
_vsntprintf_l_vsntprintf_l _vsnprintf_l_vsnprintf_l _vsnprintf_l_vsnprintf_l _vsnwprintf_l_vsnwprintf_l

要件Requirements

ルーチンによって返される値Routine 必須ヘッダー (C)Required header (C) 必須ヘッダー (C++)Required header (C++)
vsnprintf_vsnprintf_vsnprintf_lvsnprintf, _vsnprintf, _vsnprintf_l <stdio.h><stdio.h> <stdio.h> または <cstdio><stdio.h> or <cstdio>
_vsnwprintf_vsnwprintf_l_vsnwprintf, _vsnwprintf_l <stdio.h> または <wchar.h><stdio.h> or <wchar.h> <stdio.h>、<wchar.h>、<cstdio>、または <cwchar><stdio.h>, <wchar.h>, <cstdio>, or <cwchar>

_Vsnprintf_vsnprintf_l_vsnwprintf 、および _vsnwprintf_lの各関数は、Microsoft 固有の関数です。The _vsnprintf, _vsnprintf_l, _vsnwprintf and _vsnwprintf_l functions are Microsoft-specific. 互換性の詳細については、「互換性」を参照してください。For additional compatibility information, see Compatibility.

使用例Example

// crt_vsnwprintf.c
// compile by using: cl /W3 crt_vsnwprintf.c

// To turn off error C4996, define this symbol:
#define _CRT_SECURE_NO_WARNINGS

#include <stdio.h>
#include <wtypes.h>

#define BUFFCOUNT (10)

void FormatOutput(LPCWSTR formatstring, ...)
{
    int nSize = 0;
    wchar_t buff[BUFFCOUNT];
    memset(buff, 0, sizeof(buff));
    va_list args;
    va_start(args, formatstring);
    // Note: _vsnwprintf is deprecated; consider vsnwprintf_s instead
    nSize = _vsnwprintf(buff, BUFFCOUNT - 1, formatstring, args); // C4996
    wprintf(L"nSize: %d, buff: %ls\n", nSize, buff);
    va_end(args);
}

int main() {
    FormatOutput(L"%ls %ls", L"Hi", L"there");
    FormatOutput(L"%ls %ls", L"Hi", L"there!");
    FormatOutput(L"%ls %ls", L"Hi", L"there!!");
}
nSize: 8, buff: Hi there
nSize: 9, buff: Hi there!
nSize: -1, buff: Hi there!

代わりに vsnprintf を使用し、パラメータに小さな文字列を指定すると、挙動が変化します。The behavior changes if you use vsnprintf instead, along with narrow-string parameters. Countパラメーターにはバッファーのサイズ全体を指定できます。戻り値は、 countが十分に大きい場合に書き込まれた文字数です。The count parameter can be the entire size of the buffer, and the return value is the number of characters that would have been written if count was large enough:

使用例Example

// crt_vsnprintf.c
// compile by using: cl /W4 crt_vsnprintf.c
#include <stdio.h>
#include <stdarg.h> // for va_list, va_start
#include <string.h> // for memset

#define BUFFCOUNT (10)

void FormatOutput(char* formatstring, ...)
{
    int nSize = 0;
    char buff[BUFFCOUNT];
    memset(buff, 0, sizeof(buff));
    va_list args;
    va_start(args, formatstring);
    nSize = vsnprintf(buff, sizeof(buff), formatstring, args);
    printf("nSize: %d, buff: %s\n", nSize, buff);
    va_end(args);
}

int main() {
    FormatOutput("%s %s", "Hi", "there");   //  8 chars + null
    FormatOutput("%s %s", "Hi", "there!");  //  9 chars + null
    FormatOutput("%s %s", "Hi", "there!!"); // 10 chars + null
}
nSize: 8, buff: Hi there
nSize: 9, buff: Hi there!
nSize: 10, buff: Hi there!

参照See also

ストリーム入出力Stream I/O
vprintf 系関数vprintf Functions
書式指定構文: printf 関数と wprintf 関数Format Specification Syntax: printf and wprintf 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