`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`

아티클
10/12/2023

문자열에 문자를 추가합니다. 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 문자로 종료됩니다. 중복되는 문자열 간에 복사가 이뤄지면 이 동작은 정의되지 않습니다.

이거나 strDestNULLnumberOfElements 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

`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`

구문

매개 변수

반환 값

오류 조건

설명

일반 텍스트 루틴 매핑

요구 사항

예시

참고 항목

피드백

피드백

추가 리소스

strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

구문

매개 변수

반환 값

오류 조건

설명

일반 텍스트 루틴 매핑

요구 사항

예시

참고 항목

피드백

피드백

추가 리소스

`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`