strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s_mbsncat_s_l

문자열에 문자를 추가합니다. CRT의 _strncat_lstrncat보안 기능에 설명된 대로 이러한 버전의 < _mbsncat_lwcsncat_wcsncat_l_mbsncat a0/>에는 보안 기능이 향상되었습니다.

Important

Windows 런타임에서 실행되는 애플리케이션에서는 _mbsncat_s 및 _mbsncat_s_l을 사용할 수는 없습니다. 자세한 내용은 유니버설 Windows 플랫폼 앱에서 지원되지 않는 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

매개 변수

strDest
Null 종료 대상 문자열입니다.

numberOfElements
대상 버퍼의 크기입니다.

strSource
Null 종료 소스 문자열입니다.

count
추가할 문자 수 또는 _TRUNCATE.

locale
사용할 로캘입니다.

반환 값

정상적으로 실행되는 경우 0을 반환하고 오류 시에는 오류 코드를 반환합니다.

오류 조건

strDestination	numberOfElements	strSource	반환 값	strDestination의 내용
NULL 또는 종료되지 않음	any	any	EINVAL	수정 안 됨
any	any	NULL	EINVAL	수정 안 됨
any	0 또는 너무 작음	any	ERANGE	수정 안 됨

설명

이러한 함수는 strSource의 처음 D자를 strDest의 끝에 추가하려고 합니다. 여기서 D는 count와 strSource의 길이 중 더 작은 값입니다. 해당 D 문자를 추가하면 (크기가 지정된numberOfElements) 내에 strDest 들어가고 null 종결자에 대한 공간을 유지하면 원래 종료 nullstrDest부터 시작하여 해당 문자가 추가되고 새 종료 null이 추가됩니다. 그렇지 않으면 strDest[0] null 문자로 설정되고 매개 변수 유효성 검사에 설명된 대로 잘못된 매개 변수 처리기가 호출됩니다.

위의 단락에는 예외가 있습니다. 이 _TRUNCATEstrSource 경우 count 종료 null을 추가할 공간을 벗어나는 동안 적합 strDest 할 만큼 추가됩니다.

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

char dst[5];
strncpy_s(dst, _countof(dst), "12", 2);
strncat_s(dst, _countof(dst), "34567", 3);

는 버퍼 5자 길이에 3자를 두 문자에 추가하라 strncat_s 는 것을 의미합니다. null 종결자에 대한 공백을 남기지 않으므로 strncat_s 문자열을 0으로 만들고 잘못된 매개 변수 처리기를 호출합니다.

잘라내기 동작이 필요한 경우 _TRUNCATE를 사용하거나 count 매개 변수를 적절하게 조정합니다.

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

또는

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

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

이거나 strDest NULLnumberOfElements 0이면 strSource 매개 변수 유효성 검사에 설명된 대로 잘못된 매개 변수 처리기가 호출됩니다. 계속해서 실행하도록 허용된 경우 함수는 매개 변수를 수정하지 않고 EINVAL을 반환합니다.

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

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

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

이러한 함수의 디버그 라이브러리 버전은 먼저 버퍼를 0xFE 채웁니다. 이 동작을 사용하지 않도록 설정하려면 .를 사용합니다 _CrtSetDebugFillThreshold.

기본적으로 이 함수의 전역 상태는 애플리케이션으로 범위가 지정됩니다. 이 동작을 변경하려면 CRT 전역 상태를 참조하세요.

일반 텍스트 루틴 매핑

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();
}

Appending 4 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hi '
    new contents of dest: 'hi ther'

Appending 5 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hi '
    new contents of dest: 'hi there'

Appending 6 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hi '
    new contents of dest: 'hi there'

Destination buffer too small:

Appending 4 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hello '
Invalid parameter handler invoked: (L"Buffer is too small" && 0)
    new contents of dest: ''

Truncation examples:

Appending 'there' to 10-byte buffer dest with truncation semantics
    old contents of dest: 'hello '
    new contents of dest: 'hello the'
    truncation did occur

Appending '!' to 10-byte buffer dest with truncation semantics
    old contents of dest: 'hello '
    new contents of dest: 'hello !'
    truncation did not occur

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

참고 항목

문자열 조작
Locale
멀티바이트 문자 시퀀스 해석
_mbsnbcat, _mbsnbcat_l
strcat, , wcscat_mbscat
strcmp, , wcscmp_mbscmp
strcpy, , wcscpy_mbscpy
strncmp, wcsncmp, _mbsncmp_mbsncmp_l
strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy_mbsncpy_l
_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l_mbsnicmp_l
strrchr, wcsrchr, _mbsrchr_mbsrchr_l
_strset, _strset_l, _wcsset, _wcsset_l, _mbsset_mbsset_l
strspn, wcsspn, _mbsspn_mbsspn_l