wcsrtombs

書式

#include <wchar.h>

size_t wcsrtombs(char *dest, const wchar_t **src,
                 size_t len, mbstate_t *ps);

dest が NULL でなければ、 wcsrtombs() 関数はワイド文字文字列 *src を dest が指すマルチバイト文字列に変換する。最大 len バイトまでが dest に書き込まれる。シフト状態 *ps は更新される。実際の効果としては、この変換は以下の動作と同じになる: wcrtomb(dest, *src, ps) を呼び、成功が返ったら、 dest を書き込んだバイト数だけ増やし、 *src を 1 増やす。そして、wcrtomb が成功を返す限りこれを繰り返す。変換が止まる理由は 3 つ考えられる:

1.: (現在のロケールに基づいて)マルチバイト列で表現できないワイド文字に出会った場合。この場合は、 *src は不正なワイド文字を指した状態になり、 (size_t) -1 が返され、errno に EILSEQ が設定される。

2.: 長さの制限により変換が止められた場合。この場合には、*src は次に変換されるべきワイド文字列を指した状態になり、 dest に書き込まれたバイト数が返される。

3.: ワイド文字列が終端のヌルワイド文字 (L'\0') も含めて全て変換された場合。この際、 *ps が初期状態に戻るという副作用がある。この場合には *src に NULL が設定され、 dest に書き込まれたバイト数が返される (終端のヌルバイト (L'\0') は数えない)。

dest が NULL ならば len は無視されて前述のように変換が行われるが、変換されたバイトデータはメモリーに書き出されない点と、出力先の長さの制限がない点が異なる。

上記のいずれの場合も、 ps が NULL ならば、wcsrtombs() 関数だけが知っている静的な匿名の状態がシフト状態の代わりに用いられる。

プログラマは少なくとも len バイトの領域を dest に確保しなければならない。

返り値

wcsrtombs() は、変換して得られたマルチバイト列のバイト数を返す。これには終端の null バイトは含まれない。変換できないワイド文字に出会った場合には (size_t) -1 が返され、 errno に EILSEQ が設定される。

属性

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

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

GNU

wcsrtombs

名前

書式

説明

返り値

属性

準拠

注意

関連項目

この文書について

Recommended readings

Questions & Answers