wcstombs_s, _wcstombs_s_l

아티클
06/09/2015

와이드 문자의 시퀀스를 해당하는 멀티 바이트 문자의 시퀀스로 변환합니다. 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

매개 변수

[out] pReturnValue
변환 된 문자 수입니다.
[out] mbstr
결과 변환 멀티 바이트 문자열을위한 버퍼의 주소입니다.
[in]sizeInBytes
바이트에서 mbstr 버퍼의 크기입니다.
[in] wcstr
변환하는 와이드 문자열에 대한 포인터입니다.
[in] count
null 종결 문자를 포함하지 않는 mbstr 버퍼에 저장되는 와이드 문자의 최대 값 또는 _TRUNCATE
[in] locale
사용할 로캘입니다.

반환 값

성공 시 0이고, 실패 시 오류 코드입니다.

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

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

설명

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

와이드 null 문자를 발생합니다.
변환할 수 없는 와이드 문자를 발생합니다.
mbstr 버퍼에 저장되는 바이트의 수는 count 와 같습니다.

대상 문자열은 항상 null로 끝납니다. (오류의 경우에도)

count가 특별한 값 _TRUNCATE 인 경우, null 종료의 여지가 남겨진 동안 대상 버퍼에 맞도록 wcstombs_s 는 많은 문자열을 변환합니다.

wcstombs_s 가 성공적으로 소스 문자열을 변환 한 경우 ( pReturnValue 가 NULL이 아닌 경우) *pReturnValue 로 설정하고 NULL 종결자를 포함하여 변환 된 문자열의 크기를 바이트 단위로 저장합니다. mbstr 인수는 NULL 이고 필요한 버퍼 크기를 결정하는 방법을 제공하는 경우에도 발생합니다. mbstr 가 NULL 인 경우, count 는 무시 됩니다.

wcstombs_s 가 멀티 바이트 문자로 변한 될 수 없는 와이드 문자를 만나면, *pReturnValue 에 0을 넣고 대상 버퍼에 빈 문자열을 설정하고 errno 를 EILSEQ 로 설정하고 EILSEQ 를 반환합니다.

시퀀스가 wcstr 및 mbstr 중복 가리키는 경우 wcstombs_s의 동작은 정의되지 않습니다.

보안 정보
되도록 wcstr 및 mbstr 가 겹치지 않도록 하고, count 가 변환할 와이드 문자의 수를 올바르게 반영하도록 합니다.

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

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

요구 사항

루틴	필수 헤더
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 );
    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 );

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

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