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) を返し、 errno を EILSEQに設定します。

解説

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

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

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

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

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

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

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

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

例外

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

要件

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

関連項目

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