strcpy_s, wcscpy_s, _mbscpy_s

아티클
06/09/2015

문자열을 복사합니다. 이러한 버전의 strcpy, wcscpy, _mbscpy에는 CRT의 보안 기능에 설명된 대로 보안 향상 기능이 포함됩니다.

중요

_mbscpy_s는 Windows 런타임에서 실행되는 응용 프로그램에서 사용할 수 없습니다.자세한 내용은 /ZW에서 지원하지 않는 CRT 함수를 참조하십시오.

errno_t strcpy_s(
   char *strDestination,
   size_t numberOfElements,
   const char *strSource 
);
errno_t wcscpy_s(
   wchar_t *strDestination,
   size_t numberOfElements,
   const wchar_t *strSource 
);
errno_t _mbscpy_s(
   unsigned char *strDestination,
   size_t numberOfElements,
   const unsigned char *strSource 
);
template <size_t size>
errno_t strcpy_s(
   char (&strDestination)[size],
   const char *strSource 
); // C++ only
template <size_t size>
errno_t wcscpy_s(
   wchar_t (&strDestination)[size],
   const wchar_t *strSource 
); // C++ only
template <size_t size>
errno_t _mbscpy_s(
   unsigned char (&strDestination)[size],
   const unsigned char *strSource 
); // C++ only

매개 변수

strDestination
대상 문자열 버퍼의 위치입니다.
numberOfElements
대상 문자열 버퍼의 크기입니다.
strSource
Null 종료 소스 문자열 버퍼입니다.

반환 값

성공하면 0이고, 그렇지 않으면 오류입니다.

오류 조건

strDestination	numberOfElements	strSource	반환 값	strDestination의 내용입니다.
NULL	any	any	EINVAL	수정 안 됨
any	any	NULL	EINVAL	strDestination[0]을 0으로 설정합니다.
any	0 또는 너무 작습니다.	any	ERANGE	strDestination[0]을 0으로 설정합니다.

설명

strcpy_s 함수는 종료 null 문자를 포함한 strSource의 주소에 있는 콘텐츠를 strDestination으로 지정된 위치에 복사합니다. 대상 문자열은 소스 문자열과 해당 종료 null 문자를 포함할 수 있는 크기여야 합니다. 원본 영역과 대상 문자열이 겹치면 strcpy_s 동작이 지정되지 않습니다.

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

매개 변수 유효성 검사에 설명된 대로 strDestination 또는 strSource가 null 포인터이거나 대상 문자열이 너무 작은 경우 잘못된 매개 변수 처리기가 호출됩니다. 실행을 계속하도록 허용된 경우 이러한 함수는 strDestination 또는 strSource가 null 포인터이면 EINVAL을 반환하고 errno를 EINVAL로 설정하며 대상 문자열이 너무 작으면 ERANGE를 반환하고 errno를 ERANGE로 설정합니다.

성공적으로 실행될 경우 대상 문자열은 언제나 null로 끝납니다.

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

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

제네릭 텍스트 라우팅 매핑

TCHAR.H 루틴	_UNICODE 및 _MBCS 정의되지 않음	_MBCS 정의됨	_UNICODE 정의됨
_tcscpy_s	strcpy_s	_mbscpy_s	wcscpy_s

요구 사항

루틴	필수 헤더
strcpy_s	<string.h>
wcscpy_s	<string.h> 또는 <wchar.h>
_mbscpy_s	<mbstring.h>

호환성에 대한 자세한 내용은 호환성을 참조하십시오.

예제

// crt_strcpy_s.cpp
// This program uses strcpy_s and strcat_s
// to build a phrase.
//

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

int main( void )
{
   char string[80];
   // using template versions of strcpy_s and strcat_s:
   strcpy_s( string, "Hello world from " );
   strcat_s( string, "strcpy_s " );
   strcat_s( string, "and " );
   // of course we can supply the size explicitly if we want to:
   strcat_s( string, _countof(string), "strcat_s!" );
   
   printf( "String = %s\n", string );
}