mbsrtowcs

[アーティクル]
09/17/2008

更新 : 2007 年 11 月

マルチバイト文字列を対応するワイド文字列に変換します。この関数のセキュリティが強化されたバージョンについては、「mbsrtowcs」を参照してください。

size_t mbsrtowcs(
   wchar_t *wcstr,
   const char **mbstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
size_t mbsrtowcs(
   wchar_t (&wcstr)[size],
   const char **mbstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

パラメータ

[出力] wcstr
変換された結果のワイド文字列のアドレス。
[入力] mbstr
変換されるマルチバイト文字列の場所を間接的に示します。
[入力] count
変換される文字数。
[入力] mbstate
mbstate_t 変換状態オブジェクトへのポインタ。

戻り値

正常に変換された単語を返します。ただし、null で終わる単語がある場合は、null で終わる単語は返されません。エラーが発生した場合は -1 を返します。

解説

mbsrtowcs 関数は、mbstr で間接的に指された値からマルチバイト文字の文字列を変換し wcstr のアドレスに格納します。変換は、mbstate に格納されている指定された変換状態から開始します。変換は null で終わるマルチバイト文字が検出される、対応する文字が検出されなくなる、または次の文字が count に指定されている制限を超えるまで文字ごとに行われます。count に指定した値以内で mbsrtowcs がマルチバイト文字の null 文字 ('\0') を検出すると、16 ビットの null で終わる文字に変換して停止します。

したがって、wcstr のワイド文字列が null で終わるのは、mbsrtowcs が変換時にマルチバイト文字の null 文字を検出した場合だけです。mbstr と wcstr が指すシーケンスが重複する場合、mbsrtowcs の動作は未定義です。mbsrtowcs は、現在のロケールの LC_TYPE カテゴリの影響を受けます。

mbsrtowcs 関数は、再起動できるかどうかに関して、mbstowcs、_mbstowcs_l と異なります。変換状態は、同じまたは他の再起動可能な関数を後で呼び出すために mbstate に格納されます。再起動可能な関数と再起動不可能な関数を混在させた場合は、予測できない結果になる可能性があります。たとえば、その後に mbstowcs の代わりに mbsrtowcs への呼び出しを使用するアプリケーションは、mbslen の代わりに mbsrlen を使用します。

wcstr 引数が NULL の場合、mbsrtombs は変換先文字列に必要なサイズを単語数で返します。mbstate が null の場合は、内部 mbstate_t 変換状態が使用されます。wchar 文字シーケンスを対応するマルチバイト文字で表現できない場合は、-1 が返され、errno が EILSEQ に設定されます。

mbstr が NULL の場合は、「パラメータの検証」に説明されているように、無効なパラメータハンドラが呼び出されます。実行の継続が許可された場合、この関数は errno を EINVAL に設定し、-1 を返します。

C++ では、この関数にテンプレートのオーバーロードがあります。このオーバーロードは、この関数に対応するセキュリティで保護された新しい関数を呼び出します。詳細については、「セキュリティ保護されたテンプレートオーバーロード」を参照してください。