wcrtomb | Programming Place Plus　Ｃ言語編　標準ライブラリのリファレンス

概要

ワイド文字をマルチバイト文字列に変換する。

ヘッダ

wchar.h

形式

size_t wcrtomb(char* restrict s, const wchar_t w, mbstate_t* restrict ps);

引数

s

変換結果を受け取るメモリアドレス。最低でも MB_CUR_MAX以上の要素数が必要。
受け取らない場合は、ヌルポインタでも良い。

w

変換対象のワイド文字。

ps

変換状態を管理するオブジェクトへのポインタ。またはヌルポインタ。

戻り値

引数w がマルチバイト文字に変換可能であれば、引数s が指す先へ格納されたマルチバイト文字のバイト数を返す。変換可能でなければ -1 を size_t型にキャストした値を返す。

詳細

mbstate_t型の引数が追加されていることを除けば、wctomb関数と同じことを行う関数である。戻り値の内容は異なる。
引数ps は、マルチバイト文字の並びの現時点までの変換状態を管理しているオブジェクトを指す。引数ps をヌルポインタとした場合は、この関数が内部で持っている mbstate_t オブジェクトを使う。これは、プログラム開始時点で適切に初期化されている。

引数s がヌルポインタの場合、wcrtomb(内部バッファ, L'\\0', ps) のように呼び出した場合と同じ意味になる。「内部バッファ」は wcrtomb関数内部にあるバッファのことを意味する。

ワイド文字を、対応するマルチバイト文字のバイト列へ変換する。文字数としては、いずれにしても１文字であるが、マルチバイト文字としては何バイト必要とするか分からないので、char型の配列で受け取る。

引数w にヌル文字を指定した場合、mbstate_t オブジェクトの変換状態が初期状態に戻される。

変換結果が正しいワイド文字にならない場合、表現形式エラーが発生し、errno に EILSEQ が格納される。

注意

あくまで文字の変換なので、末尾に終端文字(L’\0’) は付加されない。

使用例

#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
#include <locale.h>

int main(void)
{
    const wchar_t wc = L'多';

    // LC_CTYPE をネイティブロケールに変更
    if (setlocale(LC_CTYPE, "") == NULL) {
        fputs("ロケールの設定に失敗しました。\n", stderr);
        return EXIT_FAILURE;
    }

    mbstate_t mbstate = {0};
    char mb[MB_LEN_MAX + 1];  // 全ロケールで可能性がある最大の大きさ + 末尾の '\0'

    size_ t result = wcrtomb(mb, wc, &mbstate);
    if (result == -1) {
        fputs("マルチバイト文字への変換に失敗しました。\n", stderr);
        return EXIT_FAILURE;
    }

    mb[result] = '\0';
    printf("%s\n", mb);
}

実行結果：

多

関連

mbstate_t型の引数を伴わない wctomb関数がある。
逆方向の変換であるマルチバイト文字からワイド文字への変換は、mbrtowc関数で行える。なお、終端文字のあるワイドバイト文字列からマルチバイト文字列への変換は、wcstombs関数で行える。

解説章