mbsrtowcs_s

[アーティクル]
08/09/2011

ワイド文字列をマルチバイト文字列の文字列形式に変換します。この関数は、「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 変換状態オブジェクトへのポインター。

戻り値

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

エラー条件	戻り値と errno
wcstr が NULL でsizeInWords > 0	EINVAL
mbstr が NULL です。	EINVAL
変換先バッファーが小さいため変換後の文字列が収まらない (count が _TRUNCATE の場合は例外。下記の「解説」を参照)	ERANGE

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

解説

mbsrtowcs_s 関数は、mbstr が指すマルチバイト文字列を、mbstate で示される変換状態を使用して、ワイド文字列に変換して wcstr が指すバッファーに格納します。変換は各文字列に対して行われ、次の条件の 1 つが満たされるまで続行されます。

null マルチバイト文字が検出された
無効なマルチバイト文字が検出された
wcstr バッファーに格納されたワイド文字の数が count と等しい。

変換後の文字列は、常に null で終わります (エラーの場合も同様)。

count が特殊な値の _TRUNCATE である場合、mbsrtowcs_s は、null 終端文字 1 つ分を残して、変換先バッファーに収まるだけの文字列まで変換を行います。

mbsrtowcs_s は、変換元の文字列の変換に成功すると、null 終端文字を含む変換した文字列のサイズ (ワイド文字単位) を *pReturnValue に設定します (pReturnValue が NULL でない場合)。これは、wcstr 引数が NULL の場合でも発生するので、これを使用して必要なバッファーサイズを確認できます。 wcstr が NULL の場合、count は無視されます。

mbstate がNULL の場合は、内部 mbstate_t 変換状態が使用されます。

mbsrtowcs_s は、無効なマルチバイト文字を検出すると、-1 を *pReturnValue に設定し、変換先バッファーに空の文字列を設定し、さらに、errno を EILSEQ に設定して、EILSEQ を返します。

mbstr と wcstr が指す文字列が重なり合う場合、mbsrtowcs_s 関数の動作は未定義です。 mbsrtowcs_s は、現在のロケールの LC_TYPE カテゴリの影響を受けます。

セキュリティに関するメモ
wcstr と mbstr が重なり合っていないこと、count が変換対象のマルチバイト文字数を正しく反映していることを確認してください。

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

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