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.

count
작성할 최대 문자 수입니다.Maximum number of characters to write.

format
형식 사양입니다.Format specification.

argptr
인수 목록에 대한 포인터입니다.Pointer to list of arguments.

locale
사용할 로캘입니다.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로 지정된 버퍼 크기가 formatargptr로 지정된 출력을 포함할 만큼 충분히 크지 않으면 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.

작성할 문자 수가 count보다 작거나 같으면 _vsnprintf_vsnwprintf 함수 둘 다 작성된 문자 수를 반환하고, 작성할 문자 수가 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이거나 buffer가 NULL이고 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.

설명Remarks

이러한 함수는 각각 인수 목록에 대한 포인터를 가져와서 데이터의 형식을 지정하고 count 가 가리키는 메모리에 buffer만큼의 문자를 작성합니다.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를 사용하는 경우 끝에 공간이 있는 경우에만(즉, 작성할 문자 수가 count보다 작은 경우) 버퍼가 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).

중요

특정 종류의 보안 위험을 방지하려면 format 이 사용자 정의 문자열이 아닌지 확인하세요.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 코드와의 호환성을 위해 유지됩니다.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 _vsnprintf _vsnprintf _vsnwprintf
_vsntprintf_l _vsnprintf_l _vsnprintf_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 in the Introduction.

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/O Stream I/O
vprintf 함수 vprintf Functions
형식 사양 구문: printf 및 wprintf 함수 Format Specification Syntax: printf and wprintf Functions
fprintf, _fprintf_l, fwprintf, _fwprintf_l fprintf, _fprintf_l, fwprintf, _fwprintf_l
printf, _printf_l, wprintf, _wprintf_l printf, _printf_l, wprintf, _wprintf_l
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
va_arg, va_copy, va_end, va_startva_arg, va_copy, va_end, va_start