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. バッファー サイズを指定して場合カウントで指定された出力を格納する十分な大きさでない形式定義されていますの戻り値vsnprintf記述がない場合、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. 戻り値がより大きい場合カウント- 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関数は、書き込む文字数に等しいまたはそれよりも小さいが書き込まれた文字数を返すカウント番号。書き込む文字がより大きいカウント、これら関数は出力が切り捨てられたことを示す戻り値の-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. ときにカウントが 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.

場合形式NULL、またはバッファーNULL、これらの関数は 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.

注意

呼び出すときに、終端の null 用の空きが認識されていることを確認する _vsnprintf_vsnprintf_l_vsnwprintf_vsnwprintf_lことを確認します、カウントはバッファーの長さより厳密に小さいと、関数を呼び出す前に 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 を常に書き込み、カウントパラメーター バッファーのサイズに等しい場合があります。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. 詳細については、「 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_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. カウントパラメーターは、バッファーの全体サイズを指定でき、戻り値が書き込まれた場合の文字数は、カウントサイズが十分で。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