名前

       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' (NULL ワイド文字) でなければ、 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 を増加させる必要があることを示す。

属性

   マルチスレッディング (pthreads(7) 参照)
       mbrtowc() 関数は、例外付きのスレッドセーフである。 ps パラメータが NULL で呼び出された場合
       はスレッドセーフではない。

準拠

       C99.

注意

       mbrtowc()  の動作は現在のロケールの LC_CTYPE カテゴリに依存している。

関連項目

       mbsrtowcs(3)

この文書について

       この  man ページは Linux man-pages プロジェクトのリリース 3.54 の一部 である。プロジェクト
       の説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。