mbsrtowcs

  • [アーティクル]

現在のロケールのマルチバイト文字列を、対応するワイド文字の文字列に変換します。マルチバイト文字の途中から再開することが可能です。 この関数のセキュリティが強化されたバージョンについては、「mbsrtowcs_s」を参照してください。

構文

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
変換して wcstr に格納する最大文字数 (バイト数ではない)。

mbstate
mbstate_t 変換状態オブジェクトへのポインター。 この値が null ポインターの場合、静的な内部変換状態オブジェクトが使用されます。 内部 mbstate_t オブジェクトはスレッド セーフではないので、常に独自 mbstate のパラメーターを渡すことをお勧めします。

戻り値

正常に変換された文字数を返します (終端の null 文字があっても含まれません)。 エラーが発生した場合は (size_t)(-1) を返し、次の値にEILSEQ設定しますerrno。

解説

mbsrtowcs 関数は、mbstr が間接的に指すマルチバイト文字列を、wcstr に含まれる変換状態を使用して、mbstate が指すバッファーに格納されるワイド文字に変換します。 変換は、終端の null マルチバイト文字が検出されるか、現在のロケールの有効な文字に対応しないマルチバイト シーケンスが検出されるか、文字が変換されるまで、各文字に対して count 続行されます。 mbsrtowcs は、count の発生前または発生時にマルチバイト null 文字 ('\0') を検出すると、それを 16 ビットの終端 null 文字に変換して停止します。

このため、wcstr のワイド文字の文字列が null 終了になるのは、mbsrtowcs が変換中にマルチバイト null 文字を検出した場合だけです。 mbstr および wcstr が指すシーケンスが重なり合う場合、mbsrtowcs の動作は未定義です。 mbsrtowcs は、現在のロケールの LC_TYPE カテゴリの影響を受けます。

この関数はmbsrtowcs、再起動可能性によって異_mbstowcs_lなりますmbstowcs。 同じ関数または再開可能な他の関数の後続の呼び出しのために、変換状態が mbstate に格納されます。 再開可能な関数と再開不可能な関数を混用した場合、結果は未定義です。 たとえば、後続のmbslen呼び出しが代わりに使用mbsrlenされる場合は、アプリケーションで 、 の代わりにmbstowcs使用するmbsrtowcs必要があります。

null ポインターでない場合 wcstr 、終端の null 文字に達したために変換が停止した場合、 mbstr 指すポインター オブジェクトに null ポインターが割り当てられます。 それ以外の場合は、変換された最後のマルチバイト文字の直前のアドレスが割り当てられます (存在する場合)。 これにより、後続の関数呼び出しで、この呼び出しが停止した場所で変換を再開できます。

引数が wcstr null ポインターの場合、 count 引数は無視され mbsrtowcs 、コピー先の文字列に必要なサイズをワイド文字で返します。 mbstate が null ポインターの場合、関数はスレッド セーフではない静的な mbstate_t 内部変換状態オブジェクトを使用します。 文字シーケンスmbstrに対応するマルチバイト文字表現がない場合は、-1 が返されerrnoEILSEQ、.

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

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

既定では、この関数のグローバル状態の適用対象は、アプリケーションになります。 この動作を変更するには、「CRT のグローバル状態」を参照してください。

例外

この mbsrtowcs 関数が実行されていて、引数が null ポインターでない限り、現在のスレッド内の関数が呼び出 setlocale されない限り、 mbstate 関数はマルチスレッド セーフです。

必要条件

ルーチンによって返される値 必須ヘッダー
mbsrtowcs <wchar.h>

関連項目

データ変換
ロケール
マルチバイト文字シーケンスの解釈
mbrtowc
mbtowc, _mbtowc_l
mbstowcs, _mbstowcs_l
mbsinit