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

bufferbuffer
출력을 위한 저장소 위치입니다.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.

자세한 내용은 형식 사양을 참조하세요.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 로 지정 된 출력을 포함할 만큼 충분히 크지 않으면 형식argptr의 반환 값 vsnprintf null 문자를 제외 하는 경우 작성 될 수 있는 문자 수는 count 가 충분히 클 합니다.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.

경우 형식NULL, if 또는 버퍼NULLcount 이러한 함수를 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.

설명Remarks

이러한 각 함수는 인수 목록에 대 한 포인터는 데이터의 형식을 지정 하 고를 작성 count 가리키는 메모리에 문자 버퍼합니다.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로 종료 됩니다 끝에 공간이 없는 경우에 (즉, 작성할 문자 수가 하는 경우 보다 작은 count).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수 있도록, 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 코드와의 이전 버전과 호환성을 위해 유지 됩니다.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. 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

스트림 I/OStream 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