名前

       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 │
       └─────────────────┴───────────────┴────────────────────────────┘

準拠

       POSIX.1-2001, POSIX.1-2008, C99.

注意

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

関連項目

       mbsinit(3), mbsrtowcs(3)

この文書について

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