_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l

문자열에 서식이 지정된 데이터를 씁니다.Writes formatted data to a string. 이러한 함수는 CRT의 보안 기능에 설명된 대로 강화된 보안 기능이 있는 snprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_l의 버전입니다.These are versions of snprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_l with security enhancements as described in Security Features in the CRT.

구문Syntax

int _snprintf_s(  
   char *buffer,  
   size_t sizeOfBuffer,  
   size_t count,  
   const char *format [,  
   argument] ...   
);  
int _snprintf_s_l(  
   char *buffer,  
   size_t sizeOfBuffer,  
   size_t count,  
   const char *format,  
   locale_t locale [,  
   argument] ...   
);  
int _snwprintf_s(  
   wchar_t *buffer,  
   size_t sizeOfBuffer,  
   size_t count,  
   const wchar_t *format [,  
   argument] ...   
);  
int _snwprintf_s_l(  
   wchar_t *buffer,  
   size_t sizeOfBuffer,  
   size_t count,  
   const wchar_t *format,  
   locale_t locale [,  
   argument] ...   
);  
template <size_t size>  
int _snprintf_s(  
   char (&buffer)[size],  
   size_t count,  
   const char *format [,  
   argument] ...   
); // C++ only  
template <size_t size>  
int _snwprintf_s(  
   wchar_t (&buffer)[size],  
   size_t count,  
   const wchar_t *format [,  
   argument] ...   
); // C++ only  

매개 변수Parameters

buffer
출력을 위한 저장소 위치입니다.Storage location for the output.

sizeOfBuffer
출력을 위한 저장소 위치의 크기입니다.The size of the storage location for output. _snprintf_s의 경우 bytes 단위 크기이고 _snwprintf_s의 경우 words 단위 크기입니다.Size in bytes for _snprintf_s or size in words for _snwprintf_s.

Count
저장할 최대 문자 수 또는 _TRUNCATE입니다.Maximum number of characters to store, or _TRUNCATE.

format
형식 컨트롤 문자열입니다.Format-control string.

argument
선택적 인수입니다.Optional arguments.

locale
사용할 로캘입니다.The locale to use.

반환 값Return Value

_snprintf_s는 종료 null 문자를 제외하고 buffer에 저장된 문자 수를 반환합니다._snprintf_s returns the number of characters stored in buffer, not counting the terminating null character. _snwprintf_s는 종료 null 와이드 문자를 제외하고 buffer에 저장된 와이드 문자 수를 반환합니다._snwprintf_s returns the number of wide characters stored in buffer, not counting the terminating null wide character.

데이터와 종료 null을 저장하는 데 필요한 저장소가 sizeOfBuffer를 초과하는 경우에는 매개 변수 유효성 검사에 설명된 대로 잘못된 매개 변수 처리기가 호출됩니다.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. 잘못된 매개 변수 처리기가 호출된 후에 실행을 계속하면 이러한 함수는 buffer를 빈 문자열로 설정하고 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.

buffer 또는 formatNULL 포인터이거나 count가 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.

이 오류 및 다른 오류 코드에 대한 자세한 내용은 _doserrno, errno, _sys_errlist 및 _sys_nerr을 참조하세요.For information about these and other error codes, see _doserrno, errno, _sys_errlist, and _sys_nerr.

설명Remarks

_snprintf_s 함수는 buffer에서 count 이하의 문자 서식을 지정하고 해당 문자를 저장한 다음 종료 null을 추가합니다.The _snprintf_s function formats and stores count or fewer characters in buffer and appends a terminating null. 각 인수(있는 경우)는 format의 해당 형식 사양에 따라 변환되어 출력됩니다.Each argument (if any) is converted and output according to the corresponding format specification in format. 형식은 printf 함수 패밀리와 일치합니다. 형식 사양 구문: printf 및 wprintf 함수를 참조하세요.The formatting is consistent with the printf family of functions; see Format Specification Syntax: printf and wprintf Functions. 중복되는 문자열 간에 복사가 이뤄지면 이 동작은 정의되지 않습니다.If copying occurs between strings that overlap, the behavior is undefined.

count_TRUNCATE이면 _snprintf_s는 종료 null을 위한 공간을 남겨 두고 buffer에 포함될 수 있는 만큼의 문자열을 작성합니다.If count is _TRUNCATE, then _snprintf_s writes as much of the string as will fit in buffer while leaving room for a terminating null. 종료 null을 포함한 전체 문자열을 buffer에 포함할 수 있으면 _snprintf_s는 종료 null을 포함하지 않고 작성된 문자 수를 반환합니다. 그렇지 않으면 _snprintf_s는 자르기가 수행되었음을 나타내는 -1을 반환합니다.If the entire string (with terminating null) fits in buffer, then _snprintf_s returns the number of characters written (not including the terminating null); otherwise, _snprintf_s returns -1 to indicate that truncation occurred.

중요

format 이 사용자 정의 문자열이 아닌지 확인하세요.Ensure that format is not a user-defined string.

_snwprintf_s_snprintf_s의 와이드 문자 버전이며, _snwprintf_s에 대한 포인터 인수는 와이드 문자 문자열입니다._snwprintf_s is a wide-character version of _snprintf_s; the pointer arguments to _snwprintf_s are wide-character strings. _snwprintf_s에서 인코딩 오류의 탐지 방식은 _snprintf_s에서와 다를 수 있습니다.Detection of encoding errors in _snwprintf_s might differ from that in _snprintf_s. _snwprintf_sswprintf_s와 마찬가지로 FILE 형식의 대상이 아닌 문자열에 출력을 씁니다._snwprintf_s, like swprintf_s, writes output to a string rather than to a destination of type FILE.

_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++, 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 and _MBCS not defined _MBCS 정의됨_MBCS defined _UNICODE 정의됨_UNICODE defined
_sntprintf_s _snprintf_s _snprintf_s _snwprintf_s
_sntprintf_s_l _snprintf_s_l _snprintf_s_l _snwprintf_s_l

요구 사항Requirements

루틴에서 반환된 값Routine 필수 헤더Required header
_snprintf_s, _snprintf_s_l_snprintf_s, _snprintf_s_l <stdio.h><stdio.h>
_snwprintf_s, _snwprintf_s_l_snwprintf_s, _snwprintf_s_l <stdio.h> 또는 <wchar.h><stdio.h> or <wchar.h>

호환성에 대한 자세한 내용은 소개 단원의 호환성 부분을 참조하세요.For more compatibility information, see Compatibility in the Introduction.

Example

// crt_snprintf_s.cpp  
// compile with: /MTd  

// These #defines enable secure template overloads  
// (see last part of Examples() below)  
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1   
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT 1  

#include <stdio.h>  
#include <stdlib.h>  
#include <string.h>  
#include <crtdbg.h>  // For _CrtSetReportMode  
#include <errno.h>  

// This example uses a 10-byte destination buffer.  

int snprintf_s_tester( const char * fmt, int x, size_t count )  
{  
   char dest[10];  

   printf( "\n" );  

   if ( count == _TRUNCATE )  
      printf( "%zd-byte buffer; truncation semantics\n",  
               _countof(dest) );  
   else  
      printf( "count = %zd; %zd-byte buffer\n",  
               count, _countof(dest) );  

   int ret = _snprintf_s( dest, _countof(dest), count, fmt, x );  

   printf( "    new contents of dest: '%s'\n", dest );  

   return ret;  
}  

void Examples()  
{  
   // formatted output string is 9 characters long: "<<<123>>>"  
   snprintf_s_tester( "<<<%d>>>", 121, 8 );  
   snprintf_s_tester( "<<<%d>>>", 121, 9 );  
   snprintf_s_tester( "<<<%d>>>", 121, 10 );  

   printf( "\nDestination buffer too small:\n" );  

   snprintf_s_tester( "<<<%d>>>", 1221, 10 );  

   printf( "\nTruncation examples:\n" );  

   int ret = snprintf_s_tester( "<<<%d>>>", 1221, _TRUNCATE );  
   printf( "    truncation %s occur\n", ret == -1 ? "did"  
                                                  : "did not" );  

   ret = snprintf_s_tester( "<<<%d>>>", 121, _TRUNCATE );  
   printf( "    truncation %s occur\n", ret == -1 ? "did"  
                                                  : "did not" );  
   printf( "\nSecure template overload example:\n" );  

   char dest[10];  
   _snprintf( dest, 10, "<<<%d>>>", 12321 );  
   // With secure template overloads enabled (see #defines  
   // at top of file), the preceding line is replaced by  
   //    _snprintf_s( dest, _countof(dest), 10, "<<<%d>>>", 12345 );  
   // Instead of causing a buffer overrun, _snprintf_s invokes  
   // the invalid parameter handler.  
   // If secure template overloads were disabled, _snprintf would  
   // write 10 characters and overrun the dest buffer.  
   printf( "    new contents of dest: '%s'\n", dest );  
}  

void myInvalidParameterHandler(  
   const wchar_t* expression,  
   const wchar_t* function,   
   const wchar_t* file,   
   unsigned int line,   
   uintptr_t pReserved)  
{  
   wprintf(L"Invalid parameter handler invoked: %s\n", expression);  
}  

int main( void )  
{  
   _invalid_parameter_handler oldHandler, newHandler;  

   newHandler = myInvalidParameterHandler;  
   oldHandler = _set_invalid_parameter_handler(newHandler);  
   // Disable the message box for assertions.  
   _CrtSetReportMode(_CRT_ASSERT, 0);  

   Examples();  
}  

count = 8; 10-byte buffer  
    new contents of dest: '<<<121>>'  

count = 9; 10-byte buffer  
    new contents of dest: '<<<121>>>'  

count = 10; 10-byte buffer  
    new contents of dest: '<<<121>>>'  

Destination buffer too small:  

count = 10; 10-byte buffer  
Invalid parameter handler invoked: ("Buffer too small", 0)  
    new contents of dest: ''  

Truncation examples:  

10-byte buffer; truncation semantics  
    new contents of dest: '<<<1221>>'  
    truncation did occur  

10-byte buffer; truncation semantics  
    new contents of dest: '<<<121>>>'  
    truncation did not occur  

Secure template overload example:  
Invalid parameter handler invoked: ("Buffer too small", 0)  
    new contents of dest: ''  

참고 항목See Also

스트림 I/O Stream I/O
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
fprintf, _fprintf_l, fwprintf, _fwprintf_l fprintf, _fprintf_l, fwprintf, _fwprintf_l
printf, _printf_l, wprintf, _wprintf_l printf, _printf_l, wprintf, _wprintf_l
scanf, _scanf_l, wscanf, _wscanf_l scanf, _scanf_l, wscanf, _wscanf_l
sscanf, _sscanf_l, swscanf, _swscanf_l sscanf, _sscanf_l, swscanf, _swscanf_l
vprintf 함수vprintf Functions