mbstowcs_s, _mbstowcs_s_l

  • 아티클

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

구문

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

매개 변수

pReturnValue
변환된 문자 수입니다.

wcstr
결과로 변환된 와이드 문자열을 위한 버퍼의 주소입니다.

sizeInWords
wcstr 버퍼의 크기(단어)입니다.

mbstr
null로 끝나는 멀티바이트 문자 시퀀스의 주소입니다.

count
종료 null을 포함하지 않고 버퍼에 wcstr 저장할 최대 와이드 문자 수입니다 _TRUNCATE.

locale
사용할 로캘입니다.

반환 값

성공시 0, 실패시 오류 코드.

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

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

설명

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

  • 멀티바이트 null 문자가 발견되는 경우

  • 잘못된 멀티바이트 문자가 발견되는 경우

  • wcstr 버퍼에 저장된 와이드 문자의 수가 count와 같은 경우

대상 문자열은 항상 null로 종료됩니다(오류가 있는 경우에도).

특수 값 _TRUNCATEmbstowcs_s 인 경우 count Null 종결자에 대한 공간을 유지하면서 대상 버퍼에 맞는 만큼 문자열을 변환합니다.

원본 문자열을 성공적으로 변환하면 mbstowcs_s null 종결자를 *pReturnValue 포함하여 변환된 pReturnValue 문자열의 와이드 문자로 크기를 넣습니다(제공되지 않음 NULL). 인수가 있더라도 wcstr 크기가 NULL계산되며 필요한 버퍼 크기를 확인하는 방법을 제공합니다. 이 NULLcount 면 wcstr 무시되며 sizeInWords 0이어야 합니다.

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

mbstr이 가리키는 시퀀스와 wcstr이 가리키는 시퀀스가 겹치는 경우 mbstowcs_s의 동작이 정의되지 않습니다.

Important

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

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

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

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

요구 사항

루틴에서 반환된 값 필수 헤더
mbstowcs_s <stdlib.h>
_mbstowcs_s_l <stdlib.h>

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

참고 항목

데이터 변환
Locale
MultiByteToWideChar
멀티바이트 문자 시퀀스 해석
_mbclen, mblen, _mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l