wcrtomb_s

아티클
06/09/2015

와이드 문자는 이것의 멀티 바이트 문자 표현으로 변환합니다. CRT의 보안 기능에 설명된 대로 보안 향상 기능이 포함된 wcrtomb 버전입니다.

errno_t wcrtomb_s(
   size_t *pReturnValue,
   char *mbchar,
   size_t sizeOfmbchar,
   wchar_t *wchar,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcrtomb_s(
   size_t *pReturnValue,
   char (&mbchar)[size],
   wchar_t *wchar,
   mbstate_t *mbstate
); // C++ only

매개 변수

[out] pReturnValue
기록된 바이트의 수 또는 만일 오류가 발생되었다면 -1을 반환합니다.
[out] mbchar
결과 멀티 바이트를 문자로 변환합니다.
[in] sizeOfmbchar
바이트에서 mbchar 변수의 크기입니다.
[in] wchar
변환할 와이드 문자입니다.
[in] mbstate
이 mbstate_t 개체에 대한 포인터입니다.

반환 값

0 반환하거나 만일 오류가 발생하면, errno 값을 반환합니다.

설명

wcrtomb_s 함수는 mbstate 을 포함한 지정된 변환 상태에서의 시작하여, wchar 에서 포함된 값으로부터, mbchar 로 표현되는 주소로 와이드 문자를 반환합니다. pReturnValue 값은 변환된 바이트들의 숫자가 되지만, MB_CUR_MAX 바이트들 보다 크지 않거나 오류가 발생한 경우 -1이 됩니다.

만일 mbstate 이 null인 경우, 내부적 mbstate_t 변환 상태를 사용합니다. 만일 wchar 에 포함된 문자에 해당 멀티 바이트 문자를 포함하지 않는 경우, pReturnValue 의 값은 -1이 되고 이 함수는 EILSEQ 의 errno 값을 반환할 것입니다.

wcrtomb_s 함수는 이것의 재시작 가능성이라는면에서 wctomb_s, _wctomb_s_l 과는 다릅니다. 변환 상태는 이후의 호출을 위해 같거나 다른 다시 시작할 수 있는 함수들로 mbstate 에 저장됩니다. 재 시작 가능하거나 그렇지 않은 함수들을 혼용할 때 결과들은 정의되지 않습니다. 예를 들어, wcstombs_s. 대신 wcsrtombs_s 이 사용되었다면, 응용 프로그램은 wcslen 보다 wcsrlen 을 사용합니다.

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

예외

wcrtomb_s 함수는 실행되는 동안, 현재 스레드가 setlocale 를 호출하는 함수가 필요없는 안전한 멀티스레드이고 mbstate 는 null입니다.

예제

// crt_wcrtomb_s.c
// This program converts a wide character
// to its corresponding multibyte character.
//

#include <string.h>
#include <stdio.h>
#include <wchar.h>

int main( void )
{
    errno_t     returnValue;
    size_t      pReturnValue;
    mbstate_t   mbstate;
    size_t      sizeOfmbStr = 1;
    char        mbchar = 0;
    wchar_t*    wchar = L"Q\0";

    // Reset to initial conversion state
    memset(&mbstate, 0, sizeof(mbstate));

    returnValue = wcrtomb_s(&pReturnValue, &mbchar, sizeof(char),
                            *wchar, &mbstate);
    if (returnValue == 0) {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wchar);
        printf(" was converted to a the \"%c\" ", mbchar);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}