mbstowcs_s, _mbstowcs_s_l

マルチバイト文字のシーケンスを、対応するワイド文字のシーケンスに変換します。 CRT の_mbstowcs_lmbstowcsセキュリティ機能に関する説明に従って、セキュリティが強化されたバージョン。

構文

errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count
);
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count,
   _locale_t locale
); // C++ only

パラメーター

pReturnValue
変換された文字数。

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

sizeInWords
wcstr バッファーのサイズ (単語単位)。

mbstr
NULL で終了するマルチバイト文字のシーケンスのアドレス。

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

locale
使用するロケール。

戻り値

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

エラー状態	戻り値および errno
wcstr が NULL で sizeInWords> 0	EINVAL
mbstr は NULL です	EINVAL
コピー先のバッファーが小さすぎて変換後の文字列を含めることができません (count が _TRUNCATE の場合を除きます。下記の「解説」を参照してください)	ERANGE
wcstr''NULLsizeInWords	EINVAL

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

解説

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

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

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

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

宛先文字列は常に null で終了します (エラーが発生した場合でも)。

count が特殊値 _TRUNCATE の場合、mbstowcs_s では null 終端文字用の空きを残して、ターゲット バッファーに収まる限りの文字列を変換します。

mbstowcs_sソース文字列が正常に変換されると、変換された文字列のワイド文字 (null ターミネータを含む) のサイズが (指定pReturnValueされていないNULL場合) に*pReturnValue配置されます。 このサイズは、引数が NULL、である場合wcstrでも計算され、必要なバッファー サイズを決定する方法を提供します。 の場合wcstrは countNULL無視されsizeInWords、0 である必要があります。

mbstowcs_s は、無効なマルチバイト文字が検出された場合、*pReturnValue に 0 を入れ、変換先バッファーを空の文字列に設定し、errno を EILSEQ に設定して、EILSEQ を返します。

mbstr および wcstr が指すシーケンスが重なり合う場合、mbstowcs_s の動作は未定義です。

重要

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

mbstowcs_s は、ロケールに依存するあらゆる動作に現在のロケールを使用します。_mbstowcs_s_l は、渡されたロケールを代わりに使用することを除いて同じです。 詳細については、「 Locale」を参照してください。

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

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

必要条件

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

互換性の詳細については、「 Compatibility」を参照してください。

関連項目

データ変換
ロケール
MultiByteToWideChar
マルチバイト文字シーケンスの解釈
_mbclen, mblen, _mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l