mbstowcs_s, _mbstowcs_s_l

아티클
06/09/2015

멀티 바이트 문자의 시퀀스를 해당하는 와이드 문자의 시퀀스로 변환합니다. CRT의 보안 기능에 설명된 대로 보안 향상 기능이 포함된 mbstowcs, _mbstowcs_l 버전입니다.

errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count 
);
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count 
); // C++ only
template <size_t size>
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count,
   _locale_t locale
); // C++ only

매개 변수

[out] pReturnValue
변환 된 문자 수입니다.
[out] wcstr
변환 된 와이드 문자의 결과에 대한 문자열 버퍼의 주소입니다.
[in] sizeInWords
단어에서 wcstr 버퍼의 크기입니다.
[in]mbstr
종료된 멀티 바이트 문자 null 의 시퀀스의 주소입니다.
[in] count
null 종결 문자 또는 _TRUNCATE 를 포함하지 않는 wcstr 버퍼에 저장하기 위한 와이드 문자의 최대 수입니다.
[in] locale
사용할 로캘입니다.

반환 값

성공 시 0이고, 실패 시 오류 코드입니다.

오류 조건	반환 값과 errno
wcstr 는 NULL 및 sizeInWords > 0 입니다.	EINVAL
mbstr가 NULL인 경우	EINVAL
대상 버퍼가 너무 작아 변환 된 문자열을 포함할 수 없습니다. ( count 가 _TRUNCATE 가 아닌 한, 아래 설명 참조)	ERANGE
wcstr 는 NULL 및 sizeInWords == 0 이 아닙니다.	EINVAL

이러한 조건이 발생 하는 경우, 매개 변수 유효성 검사 설명된 대로 잘못 된 매개 변수 예외를 호출합니다. 실행이 계속 되도록 혀용된 경우, 함수는 오류 코드를 반환하고 errno 를 테이블에 표시 된 대로 설정합니다.

설명

mbstowcs_s 함수는 멀티 바이트 문자열이 wcstr가 가리키는 버퍼에 저장되는 와이드 문자로 mbstr 때문에 조준 변환합니다. 이러한 조건 중 하나가 충족 될 때까지 변환은 문자마다 계속합니다.

멀티 바이트 null 문자는 발견됩니다.
잘못 된 멀티 바이트 문자가 발견 됩니다.
wcstr 에 저장된 와이드 문자의 수는 count 와 동일합니다.

대상 문자열은 항상 null로 끝납니다. (오류의 경우에도)

count가 특별한 값 _TRUNCATE 인 경우, null 종료의 여지가 남겨진 동안 대상 버퍼에 맞도록 mbstowcs_s 는 많은 문자열을 변환합니다.

만일 mbstowcs_s 가 성공적으로 소스 문자열을 변환하는 경우, 이것은 null 종결자를 포함한 변환된 문자열의 와이드 문자열의 크기를 *pReturnValue 로 넣습니다.( NULL가 아닌 pReturnValue 를 제공합니다.) wcstr 인수는 NULL 이고 필요한 버퍼 크기를 결정하는 방법을 제공하는 경우에도 발생합니다. wcstr 가 NULL 인 경우, count 는 무시되고 sizeInWords 는 0이 됩니다.

mbstowcs_s 가 잘못된 멀티 바이트 문자를 발견하는 경우, *pReturnValue 에 0을 넣고, 대상 버퍼에 빈 문자열을 설정하고 errno 를 EILSEQ 로 설정하고 EILSEQ 를 반환합니다.

만일 mbstr 와 wcstr 에 의해 가르켜진 시퀀스가 겹쳐질 경우, mbstowcs_s 의 동작은 정의되지 않습니다.

보안 정보
되도록 wcstr 및 mbstr 가 겹치지 않도록 하고, count 가 변환할 멀티바이트 문자의 수를 올바르게 반영하도록 합니다.

mbstowcs_s 는 로캘 종속 동작에 대해 현재 로캘을 사용 합니다. _mbstowcs_s_l 는 대신에 전달 된 로캘을 사용 하는 것을 제외하고는 동일합니다. 자세한 내용은 로캘을 참조하십시오.

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