mbsrtowcs_s

아티클
06/09/2015

현재 로캘의 멀티바이트 문자열을 와이드 문자열 표현으로 변환합니다. 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

매개 변수

[out] pReturnValue
변환된 문자 수입니다.
[out] wcstr
결과로 생성되는 와이드 문자열을 저장할 버퍼의 주소입니다.
[out] sizeInWords
단어 단위의 wcstr 크기(와이드 문자)입니다.
[in, out] mbstr
변환할 멀티바이트 문자열의 위치에 대한 간접 포인터입니다.
[in] count
종결 null 또는 _TRUNCATE를 포함하지 않는 wcstr 버퍼에 저장할 최대 와이드 문자 수입니다.
[in, out] 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 함수는 mbstate에 포함된 변환 상태를 사용하여 mbstr이 간접적으로 가리키는 멀티바이트 문자열을 wcstr이 가리키는 버퍼에 저장된 와이드 문자로 변환합니다. 이러한 조건 중 하나가 충족될 때까지 변환은 문자마다 계속합니다.

멀티바이트 null 문자가 발견되는 경우
잘못된 멀티바이트 문자가 발견되는 경우
wcstr 버퍼에 저장된 와이드 문자의 수가 count와 같은 경우

wcstr이 null 포인터인 경우를 제외하면 오류가 발생하더라도 대상 문자열 wcstr은 항상 null로 종결됩니다.

count가 특수 값 _TRUNCATE이면 mbsrtowcs_s는 대상 버퍼에 포함할 수 있는 만큼 문자열을 최대한 변환하되 null 종결자를 포함할 공간은 남겨 둡니다.

mbsrtowcs_s는 소스 문자열을 정상적으로 변환하는 경우 변환된 문자열의 와이드 문자 크기와 null 종결자를 *pReturnValue에 배치합니다. 이 경우 pReturnValue는 null 포인터가 아니어야 합니다. 이 작업은 wcstr 인수가 null 포인터인 경우에도 수행되므로 필요한 버퍼 크기를 결정할 수 있습니다. wcstr이 null 포인터이면 count는 무시됩니다.

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

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

mbsrtowcs_s는 현재 로캘에서 잘못된 멀티바이트 문자를 발견하면 *pReturnValue에 -1을 배치하고, 대상 버퍼 wcstr을 빈 문자열로 설정하며, errno를 EILSEQ로 설정하고 EILSEQ를 반환합니다.

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

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

mbsrtowcs_s 함수는 다시 시작할 수 있다는 점에서 mbstowcs_s, _mbstowcs_s_l와 다릅니다. 같거나 다른 다시 시작 가능 함수에 대한 후속 호출에서는 변환 상태가 mbstate에 저장됩니다. 다시 시작할 수 있는 함수와 다시 시작할 수 없는 함수를 함께 사용할 때는 결과가 정의되지 않습니다. 예를 들어 mbstowcs_s. 대신 후속 mbsrtowcs_s 호출을 사용하는 경우 응용 프로그램은 mbslen 대신 mbsrlen을 사용해야 합니다.

C++에서는 템플릿 오버로드로 이러한 함수를 간편하게 사용할 수 있습니다. 즉, 오버로드는 버퍼 길이를 자동으로 유추할 수 있으므로 크기 인수를 지정할 필요가 없습니다. 또한 기존의 비보안 함수를 그에 해당하는 안전한 최신 함수로 자동 교체할 수 있습니다. 자세한 내용은 안전한 템플릿 오버로드을 참조하십시오.