mbsrtowcsmbsrtowcs

現在のロケールのマルチバイト文字列を、対応するワイド文字の文字列に変換します。マルチバイト文字の途中から再開することが可能です。Converts a multibyte character string in the current locale to a corresponding wide character string, with the capability of restarting in the middle of a multibyte character. この関数のセキュリティが強化されたバージョンについては、「mbsrtowcs_s」をご覧ください。A more secure version of this function is available; see mbsrtowcs_s.

構文Syntax

size_t mbsrtowcs(
   wchar_t *wcstr,
   const char **mbstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
size_t mbsrtowcs(
   wchar_t (&wcstr)[size],
   const char **mbstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

パラメーターParameters

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

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

countcount
変換および格納する文字 (バイトではなく) の最大数wcstrします。The maximum number of characters (not bytes) to convert and store in wcstr.

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

正常に変換された文字数を返します (終端の null 文字があっても含まれません)。Returns the number of characters successfully converted, not including the terminating null character, if any. 返します (size_t)(-1) 場合は、エラーが発生し、設定errno EILSEQ にします。Returns (size_t)(-1) if an error occurred, and sets errno to EILSEQ.

RemarksRemarks

Mbsrtowcs関数が直接に指すマルチバイト文字の文字列に変換しますmbstrが指すバッファーに格納されているワイド文字にwcstrにより、含まれる変換状態を使用して呼び出すためします。The mbsrtowcs 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. 変換は引き続き文字ごとに、終端 null マルチバイト文字が検出された、まで、現在のロケールで有効な文字に対応しないマルチバイト シーケンスが発生しましたまで、またはカウント文字が変換されています。The conversion continues for each character until either a terminating null multibyte character is encountered, a multibyte sequence that does not correspond to a valid character in the current locale is encountered, or until count characters have been converted. 場合mbsrtowcs前に、かにマルチバイト null 文字 ('\0') が発生したカウント発生すると、16 ビット終端の null 文字を停止に変換します。If mbsrtowcs encounters the multibyte null character ('\0') either before or when count occurs, it converts it to a 16-bit terminating null character and stops.

つまり、ワイド文字の文字列wcstrが null で終わる場合にのみmbsrtowcs変換中にマルチバイト null 文字を検出するとします。Thus, the wide character string at wcstr is null-terminated only if mbsrtowcs encounters a multibyte null character during conversion. によって、シーケンスを指している場合mbstrwcstrの動作が重なるmbsrtowcsが定義されていません。If the sequences pointed to by mbstr and wcstr overlap, the behavior of mbsrtowcs is undefined. mbsrtowcsは現在のロケールの LC_TYPE カテゴリを受けます。mbsrtowcs is affected by the LC_TYPE category of the current locale.

Mbsrtowcs関数とは異なりますmbstowcs、_mbstowcs_lによってその再起動します。The mbsrtowcs function differs from mbstowcs, _mbstowcs_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の代わりに使用がmbstowcs.For example, an application should use mbsrlen instead of mbslen, if a subsequent call to mbsrtowcs is used instead of mbstowcs.

場合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.

場合、 wcstr引数が null ポインターの場合、カウント引数は無視されますとmbsrtowcsコピー先の文字列のワイド文字で、必要なサイズを返します。If the wcstr argument is a null pointer, the count argument is ignored and mbsrtowcs returns the required size in wide characters for the destination string. 場合呼び出すためnull ポインターの場合は、関数が使用する内部の非スレッド セーフな静的mbstate_t変換状態オブジェクト。If mbstate is a null pointer, the function uses a non-thread-safe static internal mbstate_t conversion state object. 場合の文字シーケンスmbstrが対応するマルチバイト文字の表現、-1 が返されます、 errnoに設定されているEILSEQします。If the character sequence mbstr does not have a corresponding multibyte character representation, a -1 is returned and the errno is set to EILSEQ.

場合mbstr 」の説明に従って、isa の null ポインター、無効なパラメーター ハンドラーが呼び出されるパラメーターの検証です。If mbstr isa null pointer, the invalid parameter handler is invoked, as described in Parameter Validation. 実行の継続が許可された場合に、この関数が設定errnoEINVAL -1 を返します。If execution is allowed to continue, this function sets errno to EINVAL and returns -1.

C++ では、この関数にテンプレートのオーバーロードがあります。このオーバーロードは、この関数に対応するセキュリティで保護された新しい関数を呼び出します。In C++, this function has a template overload that invokes the newer, secure counterpart of this function. 詳細については、「 Secure Template Overloads」を参照してください。For more information, see Secure Template Overloads.

例外Exceptions

Mbsrtowcs関数は、現在のスレッドで関数が呼び出すない限り、マルチ スレッド セーフsetlocaleこの関数を実行している限り、呼び出すため引数が null ポインターではありません。The mbsrtowcs function is multithread safe as long as 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
mbsrtowcsmbsrtowcs <wchar.h><wchar.h>

関連項目See also

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