Namespaces
Variants

wcstombs, wcstombs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
헤더 파일에 정의됨 <stdlib.h>
(1)
size_t wcstombs ( char * dst, const wchar_t * src, size_t len ) ;
(C99 이전)
size_t wcstombs ( char * restrict dst, const wchar_t * restrict src, size_t len ) ;
(C99 이후)
errno_t wcstombs_s ( size_t * restrict retval, char * restrict dst, rsize_t dstsz,
const wchar_t * restrict src, rsize_t len ) ;
(2) (C11 이후)
1) src 가 가리키는 첫 번째 요소를 시작으로 하는 배열의 와이드 문자 시퀀스를 초기 변환 상태에서 시작하는 좁은 멀티바이트 표현으로 변환합니다. 변환된 문자들은 dst 가 가리키는 char 배열의 연속된 요소들에 저장됩니다. 목적지 배열에는 최대 len 바이트까지 기록됩니다.
각 문자는 wctomb 함수 호출처럼 변환되지만, wctomb의 변환 상태는 영향을 받지 않습니다. 변환은 다음과 같은 경우 중지됩니다:
* 널 문자 L ' \0 ' 가 변환되어 저장되었습니다. 이 경우 저장된 바이트는 언시프트 시퀀스(필요한 경우)와 그 뒤에 오는 ' \0 ' 입니다.
* 현재 C 로케일에서 유효한 문자에 해당하지 않는 wchar_t 가 발견되었습니다.
* 저장될 다음 멀티바이트 문자가 len 을 초과할 경우.
만약 src 와 dst 가 겹치는 경우, 동작은 명시되어 있지 않습니다.
2) (1) 과 동일하지만, 다음 사항이 다릅니다:
* 변환은 wcrtomb 에 의한 것처럼 수행되며, wctomb 가 아닙니다
* 함수는 결과를 out-parameter로 반환합니다 retval
* 변환이 null 문자를 쓰지 않고 중단되면, 이 함수는 ' \0 ' 를 dst 의 다음 바이트에 저장합니다(이는 dst[len] 또는 dst[dstsz] 중 먼저 오는 위치일 수 있으며, 이는 최대 len+1/dstsz+1개의 전체 바이트가 기록될 수 있음을 의미합니다). 이 경우, 종료 null 앞에 unshift sequence가 기록되지 않을 수 있습니다.
* 만약 dst 가 null 포인터인 경우, 생성될 바이트 수가 * retval 에 저장됨
* 해당 함수는 종료 널 문자부터 dstsz 까지 대상 배열을 덮어씁니다
* 만약 src 와 dst 가 겹치는 경우, 동작은 명시되어 있지 않습니다.
* 다음 오류들은 런타임에 감지되며 현재 설치된 constraint handler 함수를 호출합니다:
  • retval 또는 src 가 null 포인터인 경우
  • dstsz 또는 len 이 RSIZE_MAX 보다 큰 경우 (단, dst 가 null이 아닐 때)
  • dstsz 가 0이 아닌 경우 (단, dst 가 null이 아닐 때)
  • len 이 dstsz 보다 크고 변환 과정에서 dstsz 에 도달할 때까지 src 배열에서 null 또는 인코딩 오류를 만나지 않는 경우 (단, dst 가 null이 아닐 때)
모든 bounds-checked 함수들과 마찬가지로, wcstombs_s 는 구현에 의해 __STDC_LIB_EXT1__ 가 정의되고 사용자가 __STDC_WANT_LIB_EXT1__ 를 정수 상수 1 으로 정의한 후에만 사용 가능함이 보장됩니다 <stdlib.h> 를 포함하기 전에.

목차

참고 사항

대부분의 구현에서, wcstombs 는 문자열을 처리하는 동안 mbstate_t 타입의 전역 정적 객체를 갱신하므로, 두 스레드에서 동시에 호출할 수 없습니다. 이러한 경우에는 wcsrtombs 또는 wcstombs_s 를 사용해야 합니다.

POSIX는 공통 확장을 명시합니다: 만약 dst 가 널 포인터인 경우, 이 함수는 변환되었을 때 dst 에 기록될 바이트 수를 반환합니다. 유사한 동작은 wcsrtombs 와 wcstombs_s 에서 표준입니다.

매개변수

dst - 멀티바이트 문자가 저장될 좁은 문자 배열에 대한 포인터
src - 변환할 null로 종료되는 와이드 문자열의 첫 번째 요소에 대한 포인터
len - dst가 가리키는 배열에서 사용 가능한 바이트 수
dstsz - 기록될 최대 바이트 수 ( dst 배열의 크기)
retval - 결과가 저장될 size_t 객체에 대한 포인터

반환값

1) 성공 시, dst 가 가리키는 첫 번째 요소를 시작으로 하는 문자 배열에 기록된 바이트 수(시프트 시퀀스를 포함하지만 종료 ' \0 ' 는 제외)를 반환합니다. 변환 오류 시(유효하지 않은 와이드 문자를 만난 경우), ( size_t ) - 1 를 반환합니다.
2) 성공 시 0을 반환하며(이 경우 종료 널 문자를 제외하고 dst 에 기록되었거나 기록될 바이트 수가 * retval 에 저장됨), 오류 발생 시 0이 아닌 값을 반환합니다. 런타임 제약 조건 위반 시 ( size_t ) - 1 을 * retval 에 저장하며( retval 이 null이 아닌 경우), 그리고 dst [ 0 ] 을 ' \0 ' 로 설정합니다( dst 가 null이 아니고, dstmax 가 0이 아니며 RSIZE_MAX 보다 크지 않은 경우).

예제

이 코드 실행 
#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
int main(void)
{
    // 4개의 와이드 문자
    const wchar_t src[] = L"z\u00df\u6c34\U0001f34c";
    // UTF-8에서 10바이트를 차지함
    char dst[11];
    setlocale(LC_ALL, "en_US.utf8");
    printf("wide-character string: '%ls'\n",src);
    for (size_t ndx=0; ndx < sizeof src/sizeof src[0]; ++ndx)
        printf("   src[%2zu] = %#8x\n", ndx, src[ndx]);
    int rtn_val = wcstombs(dst, src, sizeof dst);
    printf("rtn_val = %d\n", rtn_val);
    if (rtn_val > 0)
        printf("multibyte string:  '%s'\n",dst);
    for (size_t ndx=0; ndx<sizeof dst; ++ndx)
        printf("   dst[%2zu] = %#2x\n", ndx, (unsigned char)dst[ndx]);
}

출력: 

wide-character string: 'zß水🍌'
   src[ 0] =     0x7a
   src[ 1] =     0xdf
   src[ 2] =   0x6c34
   src[ 3] =  0x1f34c
   src[ 4] =        0
rtn_val = 10
multibyte string:  'zß水🍌'
   dst[ 0] = 0x7a
   dst[ 1] = 0xc3
   dst[ 2] = 0x9f
   dst[ 3] = 0xe6
   dst[ 4] = 0xb0
   dst[ 5] = 0xb4
   dst[ 6] = 0xf0
   dst[ 7] = 0x9f
   dst[ 8] = 0x8d
   dst[ 9] = 0x8c
   dst[10] =  0

참조문헌

  • C11 표준 (ISO/IEC 9899:2011):
  • 7.22.8.2 The wcstombs function (p: 360)
  • K.3.6.5.2 The wcstombs_s function (p: 612-614)
  • C99 표준 (ISO/IEC 9899:1999):
  • 7.20.8.2 The wcstombs function (p: 324)
  • C89/C90 표준 (ISO/IEC 9899:1990):
  • 4.10.8.2 The wcstombs function

참조 항목

(C95) (C11)
상태 정보를 사용하여 와이드 문자열을 좁은 멀티바이트 문자 문자열로 변환
(함수)
(C11)
좁은 멀티바이트 문자 문자열을 와이드 문자열로 변환
(함수)
C++ 문서 for wcstombs