mbstowcs_s、_mbstowcs_s_lmbstowcs_s, _mbstowcs_s_l

マルチバイト文字のシーケンスを、対応するワイド文字のシーケンスに変換します。Converts a sequence of multibyte characters to a corresponding sequence of wide characters. Security Features in the CRT」 (CRT のセキュリティ機能) で説明されているように、セキュリティが強化されたバージョンの mbstowcs、_mbstowcs_l です。Versions of mbstowcs, _mbstowcs_l with security enhancements as described in Security Features in the CRT.

構文Syntax

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

パラメーターParameters

pReturnValuepReturnValue
変換された文字数。The number of characters converted.

wcstrwcstr
結果として変換されたワイド文字の文字列のバッファーのアドレス。Address of buffer for the resulting converted wide character string.

sizeInWordssizeInWords
Wcstrバッファーのサイズ (単語単位)。The size of the wcstr buffer in words.

mbstrmbstr
null で終了するマルチバイト文字のシーケンスのアドレス。The address of a sequence of null terminated multibyte characters.

countcount
Wcstrバッファーに格納するワイド文字の最大数。終端の Null やTRUNCATEは含まれません。The maximum number of wide characters to store in the wcstr buffer, not including the terminating null, or _TRUNCATE.

localelocale
使用するロケール。The locale to use.

戻り値Return Value

正常終了した場合は 0 を返します。失敗した場合はエラー コードを返します。Zero if successful, an error code on failure.

エラー状況Error condition 戻り値とerrnoReturn value and errno
wcstrNULLで、 sizeinwords > 0wcstr is NULL and sizeInWords > 0 EINVALEINVAL
mbstrNULLですmbstr is NULL EINVALEINVAL
コピー先のバッファーが小さすぎて、変換された文字列を含めることができません ( countTRUNCATEの場合を除きます。次の「解説」を参照してください)。The destination buffer is too small to contain the converted string (unless count is _TRUNCATE; see Remarks below) ERANGEERANGE
wcstrNULLではなく、 sizeinwords = = 0wcstr is not NULL and sizeInWords == 0 EINVALEINVAL

これらのいずれかの条件が発生すると、「パラメーターの検証」で説明されているように、無効なパラメーター例外が呼び出されます。If any of these conditions occurs, the invalid parameter exception is invoked as described in Parameter Validation . 実行の継続が許可された場合、関数はエラーコードを返し、表に示されているようにerrnoを設定します。If execution is allowed to continue, the function returns an error code and sets errno as indicated in the table.

RemarksRemarks

Mbstowcs_s関数は、 mbstrが指すマルチバイト文字の文字列を、 wcstrが指すバッファーに格納されているワイド文字に変換します。The mbstowcs_s function converts a string of multibyte characters pointed to by mbstr into wide characters stored in the buffer pointed to by wcstr. これらの条件のいずれかが満たされるまで、各文字に対して変換が続きます。The conversion will continue for each character until one of these conditions is met:

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

  • 無効なマルチバイト文字が検出されました。An invalid multibyte character is encountered

  • Wcstr buffer に格納されているワイド文字の数はcountと等しくなります。The number of wide characters stored in the wcstr buffer equals count.

変換後の文字列は、常に null で終わります (エラーの場合も同様)。The destination string is always null-terminated (even in the case of an error).

Countが特別な値の切り捨てである場合、 mbstowcs_sは、null 終端文字用の空きを残したまま、コピー先のバッファーに収まる限りの文字列を変換します。If count is the special value _TRUNCATE, then mbstowcs_s converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator.

Mbstowcs_sがソース文字列を正常に変換した場合は、null 終端文字を含む、変換された文字列のサイズが、preturnvalue (指定されたpreturnvalue 値が nullではない) に * 格納されます。If mbstowcs_s successfully converts the source string, it puts the size in wide characters of the converted string, including the null terminator, into *pReturnValue (provided pReturnValue is not NULL). これは、 wcstr引数がNULLの場合にも発生し、必要なバッファーサイズを決定する手段を提供します。This occurs even if the wcstr argument is NULL and provides a way to determine the required buffer size. WcstrNULLの場合、 countは無視され、 sizeinwordsは0である必要があることに注意してください。Note that if wcstr is NULL, count is ignored, and sizeInWords must be 0.

Mbstowcs_sで無効なマルチバイト文字が検出された場合は、 *preturnvalue値に0を格納し、コピー先のバッファーを空の文字列に設定し、 errnoEILSEQに設定して、 EILSEQを返します。If mbstowcs_s encounters an invalid multibyte character, it puts 0 in *pReturnValue, sets the destination buffer to an empty string, sets errno to EILSEQ, and returns EILSEQ.

Mbstrwcstrが指すシーケンスが重なり合う場合、 mbstowcs_sの動作は未定義になります。If the sequences pointed to by mbstr and wcstr overlap, the behavior of mbstowcs_s is undefined.

重要

Wcstrmbstrが重複しないようにし、そのカウントに変換するマルチバイト文字数が正しく反映されていることを確認します。Ensure that wcstr and mbstr do not overlap, and that count correctly reflects the number of multibyte characters to convert.

mbstowcs_sは、ロケールに依存する動作に現在のロケールを使用します。 _mbstowcs_s_lは、渡されたロケールを代わりに使用する点を除いて同じです。mbstowcs_s uses the current locale for any locale-dependent behavior; _mbstowcs_s_l is identical except that it uses the locale passed in instead. 詳細については、「 Locale」を参照してください。For more information, see Locale.

C++ では、これらの関数の使用はテンプレートのオーバーロードによって簡素化されます。オーバーロードでは、バッファー長を自動的に推論できる (サイズの引数を指定する必要がなくなる) だけでなく、古くてセキュリティが万全ではない関数を新しく安全な関数に自動的に置き換えることができます。In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. 詳細については、「 Secure Template Overloads」を参照してください。For more information, see Secure Template Overloads.

必要条件Requirements

ルーチンによって返される値Routine 必須ヘッダーRequired header
mbstowcs_smbstowcs_s <stdlib.h><stdlib.h>
_mbstowcs_s_l_mbstowcs_s_l <stdlib.h><stdlib.h>

互換性の詳細については、「 互換性」を参照してください。For additional compatibility information, see Compatibility.

関連項目See also

データ変換Data Conversion
ロケールLocale
MultiByteToWideCharMultiByteToWideChar
マルチバイト文字のシーケンスの解釈Interpretation of Multibyte-Character Sequences
_mbclen、mblen、_mblen_l_mbclen, mblen, _mblen_l
mbtowc、_mbtowc_lmbtowc, _mbtowc_l
wcstombs、_wcstombs_lwcstombs, _wcstombs_l
wctomb、_wctomb_lwctomb, _wctomb_l