mbsrtowcs_s

現在のロケールのマルチバイト文字の文字列をワイド文字の文字列表現に変換します。 CRT のセキュリティ機能の説明に従って、セキュリティが強化されたmbsrtowcsのバージョン。

構文

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

パラメーター

pReturnValue
変換された文字数。

wcstr
結果として変換されたワイド文字の文字列を格納するバッファーのアドレス。

sizeInWords
wcstr のワードでのサイズ (ワイド文字)。

mbstr
変換されるマルチバイト文字の文字列の場所への間接ポインター。

count
wcstr バッファーに格納するワイド文字の最大数 (終端の null を含みません)、または _TRUNCATE。

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

戻り値

変換が正常に終了した場合は 0 を返し、失敗した場合はエラー コードを返します。

これらの条件のいずれかが発生した場合は、「パラメーターの検証で説明されているように、無効なパラメーター例外呼び出されます。 実行の続行が許可された場合、関数はエラー コードを返し、表に示すように errno を設定します。

解説

mbsrtowcs_s 関数は、mbstr が間接的に指すマルチバイト文字列を、wcstr に含まれる変換状態を使用して、mbstate が指すバッファーに格納されるワイド文字に変換します。 これらの条件のいずれかが満たされるまで、各文字に対して変換が続きます。

• マルチバイトの null 文字が検出されました。

• 無効なマルチバイト文字が検出されました。

• wcstr バッファーに格納されているワイド文字の数が count と同じです。

ターゲット文字列 wcstr は、エラーが発生した場合でも、 wcstr が null ポインターでない限り、常に null で終了します。

countが特殊な値_TRUNCATEの場合、mbsrtowcs_sは、null ターミネータの空き容量を残しながら、宛先バッファーに収まる限り多くの文字列を変換します。

ソース文字列mbsrtowcs_s正常に変換されると、変換された文字列のワイド文字のサイズが格納され、null ターミネータは null ポインターでない場合pReturnValue*pReturnValueに配置されます。 wcstr引数が null ポインターの場合でも、サイズが計算されます。これにより、必要なバッファー サイズを決定できます。 wcstrが null ポインターの場合、countは無視されます。

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

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

現在のロケールで無効なマルチバイト文字 mbsrtowcs_s 検出された場合、-1 を *pReturnValueに格納し、宛先バッファーの wcstr を空の文字列に設定し、 errno を EILSEQに設定して、 EILSEQを返します。

mbstr および wcstr が指すシーケンスが重なり合う場合、mbsrtowcs_s の動作は未定義です。 mbsrtowcs_s は、現在のロケールの LC_TYPE カテゴリの影響を受けます。

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

C++ では、この関数の使用はテンプレート オーバーロードによって簡略化されます。オーバーロードでは、バッファーの長さを自動的に推論でき (サイズ引数を指定する必要がなくなります)、セキュリティで保護されていない古い関数を新しいセキュリティで保護された関数を使用して自動的に置き換えることができます。 詳細については、「セキュリティ保護されたテンプレート オーバーロード」を参照してください。

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

例外

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

要件

関連項目

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