MULTIBYTE(3)

名称
mblen, mbstowcs, mbtowc, wcstombs, wctomb - C 言語のマルチバイト文字サポート

ライブラリ
libc

書式
<stdlib.h> int mblen(const char *mbchar, size_t nbytes) size_t mbstowcs(wchar_t *wcstring, const char *mbstring, size_t nwchars) int mbtowc(wchar_t *wcharp, const char *mbchar, size_t nbytes) size_t wcstombs(char *mbstring, const wchar_t *wcstring, size_t nbytes) int wctomb(char *mbchar, wchar_t wchar)

解説
中国語のような自然言語の基本要素は、C 言語の chars 型ひとつでは一意に表現できません。 標準 C 言語規格では、 ワイド 文字と マルチバイト 文字という、自然言語のエンコード方法の拡張を扱う 2 つの異なる方法がサポートされています。 ワイド文字は、基本要素ひとつひとつを wchar_t 型の単一オブジェクトへマップできるような内部表現です。 マルチバイト文字は入出力に使用され、C 言語の chars 型の並びとして基本要素ひとつひとつをコード化します。 マルチバイト文字では、個々の基本要素は 1 バイトまたはそれ以上(最大 MB_CHAR_MAX バイト ) にマップされます。

現在のロケール (setlocale(3)) によりワイド文字とマルチバイト文字のどちらで解釈するかが決定されます。 ロケールカテゴリ LC_CTYPE の指定によりこの解釈を制御します。 型 wchar_t は、ワイド文字を表現するにあたり、すべてのロケールに対して最大の値を収容できるだけの十分な大きさを持ちます。

マルチバイト文字列には、与えられた表現中で規定されるモード間の切り替えをするための ‘シフト’ 指示子が含まれることがあります。 明示的にシフトの発生を表すバイト列を使用すると、これらのバイトは別々の文字とはみなされずに、それと隣接する文字と一緒にまとめられます。 ‘初期’ シフト状態は区別されて、常に存在しています。 関数 mbstowcs() と wcstombs() は、マルチバイト文字列が初期シフト状態から始まって解釈されると仮定します。 関数 mblen(), mbtowc(), wctomb() は、内部で静的にシフト状態を維持管理します。 ポインタ mbchar がヌルである呼び出しでは、現在のロケールがシフト状態を必要とする場合は 0 以外が戻されます。シフト状態を必要としない場合は 0 が戻されます。 シフト状態を必要とする場合、シフト状態は初期状態にリセットされます。 LC_CTYPE か LC_ALL カテゴリを指定して setlocale() を呼び出した後では、内部シフト状態は未定義になります。

処理に便利なように、値が 0 のワイド文字 (ヌルワイド文字) は、ワイド文字列の終了として認識されます。 値が 0 の文字 (ヌルバイト) は、マルチバイト文字列の終了として認識されます。 マルチバイト文字では、ヌルバイト列は許可されていません。

関数 mblen() は、マルチバイト文字 mbchar のバイト長を算出します。 nbytes までが検査されます。

関数 mbtowc() はマルチバイト文字 mbchar をワイド文字に変換し、その結果を wcharp が指すオブジェクトに格納します。 nbytes バイトまでが検査されます。

関数 wctomb() はワイド文字 wchar をマルチバイト文字に変換し、その結果を mbchar に格納します。 mbchar が指すオブジェクトは、マルチバイト文字を収容できるだけの大きさを持たねばなりません。

関数 mbstowcs() は、マルチバイト文字列 mbstring をワイド文字列 wcstring. に変換します。 nwchars の大きさのワイド文字までしか格納されません。 終了を示すヌルワイド文字は、空きがある場合に付加されます。

関数 wcstombs() は、ワイド文字列 wcstring をマルチバイト文字列 mbstring に変換します。 nbytes バイトまでが mbstring に格納されます。 文字列の最後の断片的なマルチバイト文字は格納されません。マルチバイト文字列は、空きがあればヌルで終わります。

戻り値
現在のロケールでマルチバイト文字がサポートされていない場合、これらすべての関数は、文字を処理できる場合は -1 を返し、処理できない場合は 0 を返します。

mbchar が NULL である場合、関数 mblen(), mbtowc(), wctomb() は、シフト状態がサポートされている場合は 0 以外を返し、シフト状態がサポートされていない場合は 0 を返します。 mbchar が有効であると、これらの関数は mbchar で処理されたバイト数を返します。マルチバイト文字を認識できない場合か変換できない場合は -1 を返します。

関数 mbstowcs() は、変換されたワイド文字の数を返します。終了を示すヌルワイド文字は数に含めません。 関数 wcstombs() は、変換されたバイト数を返します。終了を示すヌルバイトは数に含めません。 不正なマルチバイト文字があると、どちらの関数も -1 を返します。

関連項目
mbrune(3), rune(3), setlocale(3), euc(4), utf2(4)

規格
関数 mblen(), mbstowcs(), mbtowc(), wcstombs() wctomb() は isoC に準拠しています。

バグ
現在のシステムは、シフト状態をサポートしません。