다음을 통해 공유

mbsrtowcs_s

  • 아티클

현재 로캘의 멀티바이트 문자열을 와이드 문자열 표현으로 변환합니다. CRT의 mbsrtowcs 보안 기능에 설명된 대로 향상된 보안 기능이 있는 버전입니다.

구문

errno_t mbsrtowcs_s(
   size_t * pReturnValue,
   wchar_t * wcstr,
   size_t sizeInWords,
   const char ** mbstr,
   size_t count,
   mbstate_t * mbstate
);
template <size_t size>
errno_t mbsrtowcs_s(
   size_t * pReturnValue,
   wchar_t (&wcstr)[size],
   const char ** mbstr,
   size_t count,
   mbstate_t * mbstate
); // C++ only

매개 변수

pReturnValue
변환된 문자 수입니다.

wcstr
결과로 생성되는 와이드 문자열을 저장할 버퍼의 주소입니다.

sizeInWords
단어 단위의 wcstr 크기(와이드 문자)입니다.

mbstr
변환할 멀티바이트 문자열의 위치에 대한 간접 포인터입니다.

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

mbstate
mbstate_t 변환 상태 개체에 대한 포인터입니다. 이 값이 null 포인터이면 정적 내부 변환 상태 개체가 사용됩니다. 내부 mbstate_t 개체는 스레드로부터 안전하지 않으므로 항상 고유한 mbstate 매개 변수를 전달하는 것이 좋습니다.

반환 값

변환이 완료되면 0이 반환되고, 실패하면 오류 코드가 반환됩니다.

오류 조건 반환 값 및 errno
wcstr 은 null 포인터이고 sizeInWords> 0입니다. EINVAL
mbstr이 null 포인터인 경우 EINVAL
간접적으로 가리키는 mbstr 문자열에는 현재 로캘에 유효하지 않은 멀티바이트 시퀀스가 포함됩니다. EILSEQ
대상 버퍼가 너무 작아서 변환된 문자열을 포함할 수 없는 경우(count가 _TRUNCATE인 경우는 제외. 자세한 내용은 설명 참조) ERANGE

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

설명

mbsrtowcs_s 함수는 mbstr에 포함된 변환 상태를 사용하여 wcstr이 간접적으로 가리키는 멀티바이트 문자열을 mbstate이 가리키는 버퍼에 저장된 와이드 문자로 변환합니다. 이러한 조건 중 하나가 충족될 때까지 변환은 문자마다 계속합니다.

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

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

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

null 포인터가 아니면 wcstr 오류가 발생하더라도 대상 문자열 wcstr 은 항상 null로 종료됩니다.

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

원본 문자열을 성공적으로 변환하면 mbsrtowcs_s 변환된 문자열의 와이드 문자로 크기를 배치하고 null 종결자를 *pReturnValuenull 포인터가 아닌 경우 pReturnValue 입력합니다. 인수가 null 포인터인 경우에도 wcstr 크기가 계산되므로 필요한 버퍼 크기를 확인할 수 있습니다. null 포인터 count 인 경우 wcstr 무시됩니다.

null 포인터가 아닌 경우 종료 null 문자에 도달하여 mbstr 변환이 중지된 경우 wcstr 가리키는 포인터 개체에 null 포인터가 할당됩니다. 그렇지 않으면 변환된 마지막 멀티바이트 문자(있는 경우)를 지나 주소가 할당됩니다. 후속 함수 호출에서 이 호출이 중지된 변환을 다시 시작할 수 있습니다.

mbstate가 null 포인터이면 라이브러리 내부 mbstate_t 변환 상태 정적 개체가 사용됩니다. 이 내부 정적 개체는 스레드로부터 안전하지 않으므로 고유한 mbstate 값을 전달하는 것이 좋습니다.

현재 로캘에서 유효하지 않은 멀티바이트 문자가 발견되면 -1*pReturnValue을 입력하고 대상 버퍼 wcstr 를 빈 문자열로 설정하고, 로 설정하고 errno EILSEQ, 반환합니다EILSEQ.mbsrtowcs_s

mbstr이 가리키는 시퀀스와 wcstr이 가리키는 시퀀스가 겹치는 경우 mbsrtowcs_s의 동작이 정의되지 않습니다. mbsrtowcs_s 는 현재 로캘의 LC_TYPE 범주에 의해 영향을 받습니다.

Important

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

함수는 mbsrtowcs_s 다시 시작 가능성에 따라 다릅니다mbstowcs_s_mbstowcs_s_l. 같거나 다른 다시 시작 가능 함수에 대한 후속 호출에서는 변환 상태가 mbstate에 저장됩니다. 다시 시작할 수 있는 함수와 다시 시작할 수 없는 함수를 함께 사용할 때는 결과가 정의되지 않습니다. 예를 들어 후속 호출 mbsrtowcs_s 이 대신 mbslen사용되는 mbstowcs_s경우 애플리케이션은 대신 사용해야 mbsrlen 합니다.

C++에서 이 함수를 사용하는 것은 템플릿 오버로드에 의해 간소화됩니다. 오버로드는 버퍼 길이를 자동으로 유추할 수 있으며(크기 인수 지정 요구 사항 제거) 최신 보안 함수를 사용하여 안전하지 않은 이전 함수를 자동으로 대체할 수 있습니다. 자세한 내용은 안전한 템플릿 오버로드를 참조하세요.

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

예외

이 mbsrtowcs_s 함수가 실행 mbstate 중이고 인수가 null 포인터가 아닌 한 현재 스레드에서 함수가 호출 setlocale 되지 않는 경우 함수는 다중 스레드로부터 안전합니다.

요구 사항

루틴에서 반환된 값 필수 헤더
mbsrtowcs_s <wchar.h>

참고 항목

데이터 변환
Locale
멀티바이트 문자 시퀀스 해석
mbrtowc
mbtowc, _mbtowc_l
mbstowcs_s, _mbstowcs_s_l
mbsinit