mblen(3)

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

標準 C ライブラリ (libc, −lc)

#include <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() は ISO/IEC 9899:1990 (‘‘ISO C89’’) に準拠しています。

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

FreeBSD 10.0 June 4, 1993 FreeBSD 10.0