wcsrtombs_s

  • 아티클

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

구문

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

매개 변수

pReturnValue
null 종결자를 포함하여 변환된 문자열의 크기(바이트)입니다.

mbstr
결과 변환된 멀티바이트 문자열에 대한 버퍼 주소입니다.

sizeInBytes
mbstr 버퍼의 크기(바이트)입니다.

wcstr
변환할 와이드 문자열을 가리킵니다.

count
버퍼에 저장할 mbstr 최대 바이트 수입니다 _TRUNCATE.

mbstate
mbstate_t 변환 상태 개체에 대한 포인터입니다.

반환 값

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

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

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

설명

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

  • null 와이드 문자가 있는 경우

  • 변환할 수 없는 와이드 문자가 발생합니다.

  • mbstr 버퍼에 저장된 바이트 수가 count와 같은 경우

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

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

원본 문자열을 성공적으로 변환하는 경우 wcsrtombs_s null 종결자를 포함하여 변환된 pReturnValue 문자열의 크기를 바이트 단위로 *pReturnValue 넣습니다(제공되지 않음NULL). 인수가라도 mbstr 크기가 계산됩니다 NULL. 필요한 버퍼 크기를 확인하는 방법을 제공합니다. 이 NULLcount 면 mbstr 무시됩니다.

멀티바이트 문자로 변환할 수 없는 와이드 문자가 발견되면 -1*pReturnValue을 배치하고, 대상 버퍼를 빈 문자열로 설정하고, 로 설정하고 errnoEILSEQ, 반환합니다EILSEQ.wcsrtombs_s

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

Important

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

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

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

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

예외

wcsrtombs_s 함수는 이 함수가 실행 중인 동안 현재 스레드의 함수가 setlocale을 호출하지 않으며 mbstate가 null이면 다중 스레드로부터 안전합니다.

예시

// crt_wcsrtombs_s.cpp
//
// This code example converts a wide
// character string into a multibyte
// character string.
//

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] =
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    errno_t         err;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
    if (err == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfully converted.\n" );
    }
}

The string was successfully converted.

요구 사항

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

참고 항목

데이터 변환
Locale
멀티바이트 문자 시퀀스 해석
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit