wcstombs_s, _wcstombs_s_l

  • 아티클

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

구문

errno_t wcstombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count
);

errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);

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

template <size_t size>
errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // C++ only

매개 변수

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

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

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

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

count
종료 null 문자를 포함하지 않고 버퍼에 mbstr 저장할 최대 바이트 수입니다 _TRUNCATE.

locale
사용할 로캘입니다.

반환 값

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

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

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

설명

wcstombs_s 함수는 wcstr가 가리키는 와이드 문자를 mbstr가 가리키는 멀티바이트 문자로 변환합니다. 이러한 조건 중 하나가 충족될 때까지 변환은 문자마다 계속합니다.

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

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

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

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

특수 값 _TRUNCATEwcstombs_s 인 경우 count Null 종결자에 대한 공간을 유지하면서 대상 버퍼에 맞는 만큼 문자열을 변환합니다. 문자열이 잘리면 반환 값이 STRUNCATE반환되고 변환이 성공한 것으로 간주됩니다.

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

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

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

Important

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

wcstombs_s는 로캘 종속 동작에 대해 현재 로캘을 사용합니다. _wcstombs_s_l은 대신 전달된 로캘을 사용하는 것을 제외하고는 wcstombs와 같습니다. 자세한 내용은 Locale을 참조하세요.

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

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

요구 사항

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

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

예시

이 프로그램은 wcstombs_s 함수의 동작을 보여 줍니다.

// crt_wcstombs_s.c
// This example converts a wide character
// string to a multibyte character string.
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t i;
    char *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    const wchar_t*pWCBuffer = L"Hello, world.";

    printf( "Convert wide-character string:\n" );

    // Conversion
    wcstombs_s(&i, pMBBuffer, (size_t)BUFFER_SIZE,
               pWCBuffer, (size_t)BUFFER_SIZE - 1); // -1 so the appended NULL doesn't fall outside the allocated buffer

    // Output
    printf("   Characters converted: %u\n", i);
    printf("    Multibyte character: %s\n\n", pMBBuffer );

    // Free multibyte character buffer
    if (pMBBuffer)
    {
        free(pMBBuffer);
    }
    
    return 0;
}

Convert wide-character string:
   Characters converted: 14
    Multibyte character: Hello, world.

참고 항목

데이터 변환
Locale
_mbclen, mblen, _mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb_s, _wctomb_s_l
WideCharToMultiByte