strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

아티클
06/09/2015

문자열에 문자를 추가합니다. 이러한 버전의 strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l에는 CRT의 보안 기능에 설명된 대로 보안 향상 기능이 포함됩니다.

중요

_mbsncat_s 와 _mbsncat_s_l 는 Windows 런타임에서 실행되는 어플리케이션에서는 사용될 수 없습니다.자세한 내용은 /ZW에서 지원하지 않는 CRT 함수를 참조하십시오.

errno_t strncat_s(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count
);
errno_t _strncat_s_l(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count,
   _locale_t locale
);
errno_t wcsncat_s(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count 
);
errno_t _wcsncat_s_l(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
);
errno_t _mbsncat_s(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count
);
errno_t _mbsncat_s_l(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t strncat_s(
   char (&strDest)[size],
   const char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _strncat_s_l(
   char (&strDest)[size],
   const char *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t wcsncat_s(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count 
); // C++ only
template <size_t size>
errno_t _wcsncat_s_l(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t _mbsncat_s(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbsncat_s_l(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
); // C++ only

매개 변수

[out] strDest
Null-종료된 대상 문자열.
[in]numberOfElements
대상 버퍼의 크기입니다.
[in]strSource
Null 종료 소스 문자열입니다.
[in]count
추가 혹은 _TRUNCATE 할 문자 수입니다.
[in] locale
사용할 로캘입니다.

반환 값

성공 시 0을 반환하고, 실패 시 오류 코드입니다.

오류 조건

strDestination	numberOfElements	strSource	반환 값	strDestination의 내용입니다.
NULL 나 종료 되지 않은	any	any	EINVAL	수정 안 됨
any	any	NULL	EINVAL	수정 안 됨
any	0 또는 너무 작습니다.	any	ERANGE	수정 안 됨

설명

이러한 함수는, D 이 count 과 strSource 길이 보더 더 적은 곳에 있는 , strDest 의 끝에 있는 strSource 의 첫 D 문자를 추가를 시도합니다. 그 D 문자가 ( numberOfElements로 크기가 지정된) strDest 내부에 꽉 맞거나 null 종료 공간에서 여전히 떠날 수 있는 경우, 그러면 그 문자는 추가되고, strDest의 원래 null 종료로 시작하고, 새로운 종료 nul은 추가됩니다; 그렇지 않으면, strDest[0]은 매개 변수 유효성 검사로 설명한데로 null문자와 유효하지 않는 매개 변수 처리기를 추가되고 설정합니다.

위의 단락에 예외가 있습니다. 만약 count 이 _TRUNCATE 인 경우 종료 null 이 추가되는 공간을 여전히 남겨둔 체 그러면 맞춤에 strSource 가 strDest 가 추가되는 것이 많습니다.

예를 들면 다음과 같습니다.

char dst[5];

strncpy_s(dst, _countof(dst), "12", 2);

strncat_s(dst, _countof(dst), "34567", 3);

다섯 문자의 길이 버퍼안의 두 문자에서 세 문자로 추가된 strncat_s 의미합니다; 이는 null 종결자의 공간 없이 떠날 수 없으므로, strncat_s 0은 문자열을 출력하고 잘못된 매개 변수 처리기를 호출합니다.

잘라내기 동작이 필요한 경우, _TRUNCATE 을 사용하거나 size 매개 변수가 덧붙여져 조정합니다 :

strncat_s(dst, _countof(dst), "34567", _TRUNCATE);

또는

strncat_s(dst, _countof(dst), "34567", _countof(dst)-strlen(dst)-1);

모든 경우에서, 결과 문자열은 null 문자로 종료 됩니다. 중복되는 문자열 간에 복사가 이뤄지면 이 동작은 정의되지 않습니다.

이 strSource 혹은 strDest 이 NULL 이거나 numberOfElements 이 0인 경우, 매개 변수 유효성 검사 에 설명된 대로 잘못된 매개 변수 처리기가 호출됩니다. 실행이 계속 허용되지 않는 경우, 함수는 매개 변수가 수정됨이 없이 EINVAL 을 반환합니다.

wcsncat_s 및 _mbsncat_s 는 와이드 문자 및 strncat_s의 멀티 바이트 문자 버전입니다. 이 wcsncat_s 의 인수 및 반환 값은 와이드 문자열이며, _mbsncat_s 는 멀티바이트 문자열입니다. 그렇지 않으면 이들 세 함수는 동일하게 작동합니다.

출력 값은 로캘의 LC_CTYPE 범주 설정에 영향을 받습니다. 자세한 내용은 setlocale을 참조하십시오. _l 접미사가 없는 이러한 함수 버전은 이 로캘 종속 동작에 현재 로캘을 사용하며, _l 접미사가 있는 버전은 전달된 로캘 매개 변수를 대신 사용하는 경우를 제외하고는 동일합니다. 자세한 내용은 로캘을 참조하십시오.

C++에서는 템플릿 오버로드로 인해 이러한 함수를 사용하는 것이 보다 간단해 집니다. 오버로드는 버퍼 길이를 자동으로 유추할 수 있으며(크기 인수를 지정할 필요가 없어짐), 기존의 비보안 함수를 보다 최신의 보안 대응 함수로 자동으로 바꿀 수 있습니다. 자세한 내용은 안전한 템플릿 오버로드을 참조하십시오.

이러한 함수의 디버그 버전은 우선 0xFD로 버퍼를 채웁니다. 이 동작을 사용하지 않으려면 _CrtSetDebugFillThreshold를 사용하십시오.

제네릭 텍스트 라우팅 매핑

TCHAR.H 루틴	_UNICODE 및 _MBCS 정의되지 않음	_MBCS 정의됨	_UNICODE 정의됨
_tcsncat_s	strncat_s	_mbsnbcat_s	wcsncat_s
_tcsncat_s_l	_strncat_s_l	_mbsnbcat_s_l	_wcsncat_s_l

_strncat_s_l 및 _wcsncat_s_l 은 로캘 의존성이 없습니다; 이들은 _tcsncat_s_l 만 제공됩니다.

요구 사항

루틴	필수 헤더
strncat_s	<string.h>
wcsncat_s	<string.h> 또는 <wchar.h>
_mbsncat_s, _mbsncat_s_l	<mbstring.h>

추가 호환성 정보는 호환성을 참조하십시오.

예제

// crt_strncat_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.

errno_t strncat_s_tester( const char * initialDest,
                          const char * src,
                          int count )
{
   char dest[10];
   strcpy_s( dest, _countof(dest), initialDest );

   printf_s( "\n" );

   if ( count == _TRUNCATE )
      printf_s( "Appending '%s' to %d-byte buffer dest with truncation semantics\n",
               src, _countof(dest) );
   else
      printf_s( "Appending %d chars of '%s' to %d-byte buffer dest\n",
              count, src, _countof(dest) );

   printf_s( "    old contents of dest: '%s'\n", dest );

   errno_t err = strncat_s( dest, _countof(dest), src, count );

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

   return err;
}


void Examples()
{
   strncat_s_tester( "hi ", "there", 4 );
   strncat_s_tester( "hi ", "there", 5 );
   strncat_s_tester( "hi ", "there", 6 );

   printf_s( "\nDestination buffer too small:\n" );
   strncat_s_tester( "hello ", "there", 4 );

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

   errno_t err = strncat_s_tester( "hello ", "there", _TRUNCATE );
   printf_s( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   err = strncat_s_tester( "hello ", "!", _TRUNCATE );
   printf_s( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   printf_s( "\nSecure template overload example:\n" );

   char dest[10] = "cats and ";
   strncat( dest, "dachshunds", 15 );
   // With secure template overloads enabled (see #define
   // at top of file), the preceding line is replaced by
   //    strncat_s( dest, _countof(dest), "dachshunds", 15 );
   // Instead of causing a buffer overrun, strncat_s invokes
   // the invalid parameter handler.
   // If secure template overloads were disabled, strncat would
   // append "dachshunds" and overrun the dest buffer.
   printf_s( "    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_s(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();
}