mbsrtowcs_smbsrtowcs_s

現在のロケールのマルチバイト文字の文字列をワイド文字の文字列表現に変換します。Convert a multibyte character string in the current locale to its wide character string representation. これは、「CRT のセキュリティ機能」の説明にあるとおりセキュリティーが強化されたバージョンの mbsrtowcs です。A version of mbsrtowcs with security enhancements as described in Security Features in the CRT.

構文Syntax

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

パラメーターParameters

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

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

sizeInWordssizeInWords
サイズwcstr単語 (ワイド文字)。The size of wcstr in words (wide characters).

mbstrmbstr
変換されるマルチバイト文字の文字列の場所への間接ポインター。Indirect pointer to the location of the multibyte character string to be converted.

countcount
格納するワイド文字の最大数、 wcstrバッファー、終端の null は含まないまたは_TRUNCATEします。The maximum number of wide characters to store in the wcstr buffer, not including the terminating null, or _TRUNCATE.

mbstatembstate
ポインター、 mbstate_t変換状態オブジェクト。A pointer to an mbstate_t conversion state object. この値が null ポインターの場合、静的な内部変換状態オブジェクトが使用されます。If this value is a null pointer, a static internal conversion state object is used. 内部mbstate_tオブジェクトはスレッド セーフではありませんを常に渡す独自ことをお勧めします。呼び出すためパラメーター。Because the internal mbstate_t object is not thread-safe, we recommend that you always pass your own mbstate parameter.

戻り値Return Value

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

エラー条件Error condition 戻り値およびerrnoReturn value and errno
wcstr null ポインターとsizeInWords > 0wcstr is a null pointer and sizeInWords > 0 EINVALEINVAL
mbstr null ポインターmbstr is a null pointer EINVALEINVAL
文字列直接に指すmbstr現在のロケールの無効なマルチバイト シーケンスが含まれています。The string indirectly pointed to by mbstr contains a multibyte sequence that is not valid for the current locale. EILSEQEILSEQ
コピー先のバッファーが小さすぎて変換後の文字列を含む (しない限り、カウント_TRUNCATE; 詳細については、「解説」を参照してください)The destination buffer is too small to contain the converted string (unless count is _TRUNCATE; for more information, see Remarks) ERANGEERANGE

これらのいずれかの条件が発生すると、「パラメーターの検証」に説明されているとおり無効なパラメーター例外が呼び出されます。If any one 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

Mbsrtowcs_s関数が直接に指すマルチバイト文字の文字列に変換しますmbstrが指すバッファーに格納されているワイド文字にwcstrにより、含まれる変換状態を使用して呼び出すためします。The mbsrtowcs_s function converts a string of multibyte characters indirectly pointed to by mbstr into wide characters stored in the buffer pointed to by wcstr, by using the conversion state contained in mbstate. これらの条件のいずれかが満たされるまで、各文字に対して変換が続きます。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 equals をバッファーカウントします。The number of wide characters stored in the wcstr buffer equals count.

コピー先文字列wcstrは常にエラー発生時でも、null で終わる場合を除き、 wcstr null ポインターです。The destination string wcstr is always null-terminated, even in the case of an error, unless wcstr is a null pointer.

場合カウント特殊な値は、 _TRUNCATEmbsrtowcs_sコピー先のバッファーは null の空きを残して収まる限りの文字列の多くに変換されますターミネータ。If count is the special value _TRUNCATE, mbsrtowcs_s converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator.

場合mbsrtowcs_s 、元の文字列を正常に変換の変換後の文字列とに終端の null ワイド文字のサイズが置かれる *pReturnValueに用意されているpReturnValue null ポインターではありません。If mbsrtowcs_s successfully converts the source string, it puts the size in wide characters of the converted string and the null terminator into *pReturnValue, provided pReturnValue is not a null pointer. これが発生した場合でも、 wcstr引数が null ポインターであり、必要なバッファー サイズを決定することができます。This occurs even if the wcstr argument is a null pointer and lets you determine the required buffer size. その場合に注意してくださいwcstr null ポインターの場合は、カウントは無視されます。Note that if wcstr is a null pointer, count is ignored.

場合wcstrが null ポインターを指すポインター オブジェクトmbstr終端の null 文字に達したために、変換が停止している場合に null ポインターが割り当てられます。If wcstr is not a null pointer, the pointer object pointed to by mbstr is assigned a null pointer if conversion stopped because a terminating null character was reached. それ以外の場合、変換された最後のマルチバイト文字がある場合は、その後ろのアドレスが割り当てられます。Otherwise, it is assigned the address just past the last multibyte character converted, if any. これにより、後続の関数呼び出しで、この呼び出しが停止した場所から変換を再開できます。This allows a subsequent function call to restart conversion where this call stopped.

場合呼び出すためが null ポインターの場合、ライブラリの内部mbstate_t変換状態の静的オブジェクトを使用します。If mbstate is a null pointer, the library internal mbstate_t conversion state static object is used. 渡す独自ことをお勧めこの内部静的オブジェクトはスレッド セーフではないため、呼び出すため値。Because this internal static object is not thread-safe, we recommend that you pass your own mbstate value.

場合mbsrtowcs_sマルチバイト文字の現在のロケールが無効ですが検出されたに-1 を入れ *pReturnValue、コピー先のバッファーを設定wcstr空の文字列に次のように設定します。 errnoEILSEQ、し、返しますEILSEQします。If mbsrtowcs_s encounters a multibyte character that is not valid in the current locale, it puts -1 in *pReturnValue, sets the destination buffer wcstr to an empty string, sets errno to EILSEQ, and returns EILSEQ.

によって、シーケンスを指している場合mbstrwcstrの動作が重なるmbsrtowcs_sが定義されていません。If the sequences pointed to by mbstr and wcstr overlap, the behavior of mbsrtowcs_s is undefined. mbsrtowcs_sは現在のロケールの LC_TYPE カテゴリを受けます。mbsrtowcs_s is affected by the LC_TYPE category of the current locale.

重要

いることを確認wcstrmbstr重複しないと変換するマルチバイト文字の数を正確に反映します。Ensure that wcstr and mbstr do not overlap, and that count correctly reflects the number of multibyte characters to convert.

Mbsrtowcs_s関数とは異なりますmbstowcs_s、_mbstowcs_s_lによってその再起動します。The mbsrtowcs_s function differs from mbstowcs_s, _mbstowcs_s_l by its restartability. 変換の状態が格納されている呼び出すため同じか、またはその他の再開可能な関数を呼び出すのためです。The conversion state is stored in mbstate for subsequent calls to the same or other restartable functions. 再開可能な関数と再開不可能な関数を混用した場合、結果は未定義です。Results are undefined when mixing the use of restartable and nonrestartable functions. たとえば、アプリケーションで使用するmbsrlenの代わりにmbslen後続の呼び出しの場合は、 mbsrtowcs_sの代わりに使用がmbstowcs_s.For example, an application should use mbsrlen instead of mbslen, if a subsequent call to mbsrtowcs_s is used instead of mbstowcs_s.

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

例外Exceptions

Mbsrtowcs_s場合、現在のスレッドの呼び出しでない関数、関数はマルチ スレッド セーフsetlocaleこの関数を実行している限り、呼び出すため引数は、null ポインターではありません。The mbsrtowcs_s function is multithread safe if no function in the current thread calls setlocale as long as this function is executing and the mbstate argument is not a null pointer.

必要条件Requirements

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

関連項目See also

データ変換Data Conversion
ロケールLocale
マルチバイト文字のシーケンスの解釈Interpretation of Multibyte-Character Sequences
mbrtowcmbrtowc
mbtowc、_mbtowc_lmbtowc, _mbtowc_l
mbstowcs_s、_mbstowcs_s_lmbstowcs_s, _mbstowcs_s_l
mbsinitmbsinit