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
wcstr は null ポインターで、 sizeInWords> 0 EINVAL
mbstr が null ポインター EINVAL
間接的に指し示される mbstr 文字列には、現在のロケールでは無効なマルチバイト シーケンスが含まれています。 EILSEQ
コピー先のバッファーが小さすぎて変換後の文字列を含めることができません (count が _TRUNCATE の場合を除きます。詳細については、「解説」を参照してください。)。 ERANGE

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

解説

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

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

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

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

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

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

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

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

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

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

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

重要

wcstr と mbstr が重なり合わず、変換するマルチバイト文字の数が count に適切に反映されていることを確認します。

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

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

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

例外

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

必要条件

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

関連項目

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