名前

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

準拠

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

注意

       wcsrtombs()  の動作は現在のロケールの LC_CTYPE カテゴリーに依存する。

       ps に NULL を渡した際の動作はマルチスレッドセーフでない。

関連項目

       iconv(3), mbsinit(3), wcrtomb(3), wcsnrtombs(3), wcstombs(3)

この文書について

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