mbrtowc

書式

#include <wchar.h>

size_t mbrtowc(wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);

この関数が用いられる場合、通常 s が NULL でなく pwc も NULL でない。この場合は、 mbrtowc() 関数は s から始まる最大 n バイトのマルチバイト文字を検査して、次の完全なマルチバイト文字列を取り出し、それをワイド文字に変換して *pwc に格納する。同時にシフト状態 *ps を更新する。変換したワイド文字が L'\0' (ヌルワイド文字) でなければ、 s から消費するバイト数を返す。変換したワイド文字が L'\0' の場合にはシフト状態 *ps を初期状態に戻して 0 を返す。

s から始まる n バイトが完全なマルチバイト文字を含んでいない場合には、 mbrtowc() は (size_t) -2 を返す。マルチバイト文字列に冗長なシフトシーケンスが含まれていると、 n >= MB_CUR_MAX の時にもこのようなことが起こりえる。

s から始まるマルチバイト文字列が、次の完全な文字の前に不正なマルチバイト列を含んでいる場合には、 mbrtowc() は (size_t) -1 を返し、 errno に EILSEQ を設定する。この場合は *ps への影響は未定義である。

s が NULL でなく pwc が NULL の場合は mbrtowc() 関数は上記と同様に動作するが、変換したワイド文字はメモリーには書き込まれない。

puts *ps in the initial state and returns 0. 三番目の場合として s が NULL の場合、 pwc と n は無視される。 *ps が表現する変換状態が不完全なマルチバイト文字変換を示している場合は、 mbrtowc() 関数は (size_t) -1 を返し、 errno に EILSEQ をセットし、 *ps は未定義状態のままにする。さもなければ、 mbrtowc() 関数は *ps を初期状態にして 0 を返す。

上記の全ての場合において、 ps が NULL ならば代わりに mbrtowc() 関数のみが使用する静的で名前のない状態が使用される。さもなければ、 *ps は有効な mbstate_t オブジェクトでなければならない。 mbstate_t オブジェクトである a はゼロで埋めることによって初期状態に初期化できる。以下に例を示す。

memset(&a, 0, sizeof(a));

返り値

L'\0' 以外のワイド文字を認識した場合には mbrtowc() 関数は s から始まるマルチバイト列から解析したバイト数を返す。 L'\0' ワイド文字を認識した場合には 0 を返す。不正なマルチバイト列に遭遇した場合には (size_t) -1 を返し、 errno に EILSEQ を設定する。完全なマルチバイト文字を解析できなかった場合には (size_t) -2 を返し n を増加させる必要があることを示す。

属性

この節で使用されている用語の説明については、 attributes(7) を参照。

インターフェース	属性	値
mbrtowc()	Thread safety	MT-Unsafe race:mbrtowc/!ps

GNU

mbrtowc

名前

書式

説明

返り値

属性

準拠

注意

関連項目

この文書について

Recommended readings

Questions & Answers