名前

wcsnrtombs -ワイド文字文字列をマルチバイト文字列に変換する

書式

#include <wchar.h>
size_t wcsnrtombs(char * dest , const wchar_t ** src , size_t nwc ,
size_t len , mbstate_t * ps );

glibc 向けの機能検査マクロの要件 ( feature_test_macros(7) 参照):
wcsnrtombs():

説明

wcsnrtombs() 関数は、 wcsrtombs() 関数に似ている。ただし、変換されるワイド文字の数が( *src から数えて) nwc 文字に制限されている点が異なる。

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

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

2. NULL ワイド文字 (L'\0') に出会わないで nwc 個のワイド文字を変換した場合か、長さの制限によって変換が止められた場合。この場合には、 *src は次に変換されるべきワイド文字を指した状態になり、 dest に書き込まれたバイト数が返される。

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

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

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

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

返り値

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

準拠

POSIX.1-2008.

注意

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

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

関連項目

iconv(3), wcsrtombs(3)

この文書について

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