strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l

아티클
06/09/2015

한 문자열의 문자를 다른 위치로 복사 이러한 버전의 strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l에는 CRT의 보안 기능에 설명된 대로 보안 향상 기능이 포함됩니다.

중요

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

errno_t strncpy_s(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count
);
errno_t _strncpy_s_l(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count,
   _locale_t locale
);
errno_t wcsncpy_s(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count 
);
errno_t _wcsncpy_s_l(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
);
errno_t _mbsncpy_s(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count 
);
errno_t _mbsncpy_s_l(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count,
   locale_t locale
);
template <size_t size>
errno_t strncpy_s(
   char (&strDest)[size],
   const char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _strncpy_s_l(
   char (&strDest)[size],
   const char *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t wcsncpy_s(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count 
); // C++ only
template <size_t size>
errno_t _wcsncpy_s_l(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t _mbsncpy_s(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count 
); // C++ only
template <size_t size>
errno_t _mbsncpy_s_l(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count,
   locale_t locale
); // C++ only

매개 변수

strDest
대상 문자열입니다.
numberOfElements
문자열에 있는 대상 문자열의 크기입니다.
strSource
소스 문자열입니다.
count
복사될 또는 _TRUNCATE 문자의 수입니다.
locale
사용할 로캘입니다.

반환 값

성공 하면 0, 잘림이 발생하면 STRUNCATE, 그렇지 않으면 오류 코드입니다.

오류 조건

strDest	numberOfElements	strSource	반환 값	strDest의 내용입니다.
NULL	any	any	EINVAL	수정 안 됨
any	any	NULL	EINVAL	strDest[0]은 0으로 설정합니다.
any	0	any	EINVAL	수정 안 됨
NULL이 아닙니다.	너무 작습니다.	any	ERANGE	strDest[0]은 0으로 설정합니다.

설명

이러한 함수는 D 가 count 및 strSource의 길이 보다 작은 곳에서, strSource 의 첫 번째 D 문자를 strDest로 복사합니다. 만약 이러한 D 문자가 strDest (크기가 numberOfElements로 주어진) 안에 들어갈 수 있고 여전히 공간이 null로 종료된다면, 문자가 복사되고 null이 추가되어 종료됩니다; 그렇지 않으면 strDest[0]은 null 문자를 설정하고 잘못된 매개 변수 처리기가 매개 변수 유효성 검사에 설명된대로 호출됩니다.

위의 단락에 예외가 있습니다. 만약 count 가 _TRUNCATE이면, 추가된 null로 끝나는 공간을 남겨둔 채로 다음 strSource 의 크기만큼 strDest 로 복사됩니다.

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

char dst[5];

strncpy_s(dst, 5, "a long string", 5);

분명히 우리는 버퍼의 5바이트 만큼 strncpy_s 를 호출하여 다섯 문자를 복사합니다.; null 종결자에 대한 공백이 없고, 따라서 strncpy_s zeroes가 출력되고 잘못된 매개 변수 처리기를 호출합니다.

사용할 잘라내기 동작 필요한 경우 _TRUNCATE 또는 (size - 1)을 사용합니다:

strncpy_s(dst, 5, "a long string", _TRUNCATE);

strncpy_s(dst, 5, "a long string", 4);

strncpy와 달리, 만약 count 이 strSource 의 길이보다 크면, 대상 문자열은 null 문자의 길이가 count 의 길이까지 채워지지 않습니다.

원본 영역과 대상 문자열이 겹치면 strncpy_s 동작이 지정되지 않습니다.

strDest 및 strSource 가 NULL 이고 numberOfElements 이 0인경우, 잘못된 매개 변수 처리기가 호출됩니다. 계속해서 실행하도록 허용된 경우, 함수는 EINVAL 를 반환하고 errno 을 EINVAL으로 설정합니다.

wcsncpy_s 및 _mbsncpy_s 는 와이드 문자 및 strncpy_s의 멀티 바이트 문자 버전입니다. wcsncpy_s 및 mbsncpy_s의 인수 및 반환값은 그에 따라 달라 집니다. 그렇지 않으면 이들 여섯 함수는 동일하게 작동합니다.

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

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

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

제네릭 텍스트 라우팅 매핑

TCHAR.H 루틴	_UNICODE 및 _MBCS 정의되지 않음	_MBCS 정의됨	_UNICODE 정의됨
_tcsncpy_s	strncpy_s	_mbsnbcpy_s	wcsncpy_s
_tcsncpy_s_l	_strncpy_s_l	_mbsnbcpy_s_l	_wcsncpy_s_l

참고

_strncpy_s_l, _wcsncpy_s_l 및 _mbsncpy_s_l 는 로캘 종속 하지않고 _tcsncpy_s_l 에 대해 제공되고 직접 호출될 수 없습니다.

요구 사항

루틴	필수 헤더
strncpy_s, _strncpy_s_l	<string.h>
wcsncpy_s, _wcsncpy_s_l	<string.h> 또는 <wchar.h>
_mbsncpy_s, _mbsncpy_s_l	<mbstring.h>

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

예제

// crt_strncpy_s_1.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 strncpy_s_tester( const char * src,
                          int count )
{
   char dest[10];

   printf( "\n" );

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

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

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

   return err;
}


void Examples()
{
   strncpy_s_tester( "howdy", 4 );
   strncpy_s_tester( "howdy", 5 );
   strncpy_s_tester( "howdy", 6 );

   printf( "\nDestination buffer too small:\n" );
   strncpy_s_tester( "Hi there!!", 10 );

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

   errno_t err = strncpy_s_tester( "How do you do?", _TRUNCATE );
   printf( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   err = strncpy_s_tester( "Howdy.", _TRUNCATE );
   printf( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

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

   char dest[10];
   strncpy( dest, "very very very long", 15 );
   // With secure template overloads enabled (see #defines at
   // top of file), the preceding line is replaced by
   //    strncpy_s( dest, _countof(dest), "very very very long", 15 );
   // Instead of causing a buffer overrun, strncpy_s invokes
   // the invalid parameter handler.
   // If secure template overloads were disabled, strncpy would
   // copy 15 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();
}

// crt_strncpy_s_2.c
// contrasts strncpy and strncpy_s

#include <stdio.h>
#include <stdlib.h>

int main( void )
{
   char a[20] = "test";
   char s[20];

   // simple strncpy usage:

   strcpy_s( s, 20, "dogs like cats" );
   printf( "Original string:\n   '%s'\n", s );

   // Here we can't use strncpy_s since we don't 
   // want null termination
   strncpy( s, "mice", 4 );
   printf( "After strncpy (no null-termination):\n   '%s'\n", s );
   strncpy( s+5, "love", 4 );
   printf( "After strncpy into middle of string:\n   '%s'\n", s );

   // If we use strncpy_s, the string is terminated 
   strncpy_s( s, _countof(s), "mice", 4 );
   printf( "After strncpy_s (with null-termination):\n   '%s'\n", s );

}