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_sA 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
最大字符数 (不字节数) 将转换并将存储在wcstrThe 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对象不是线程安全,我们建议始终传递你自己mbstate参数。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.

备注Remarks

Mbsrtowcs函数将转换的间接指向的多字节字符字符串mbstr,到指向的缓冲区中存储的宽字符wcstr,也可由使用中包含的转换状态mbstateThe 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. 转换状态存储在mbstate以便后续调用相同的或其他可重启函数。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. 如果mbstate是 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设置为EILSEQIf the character sequence mbstr does not have a corresponding multibyte character representation, a -1 is returned and the errno is set to EILSEQ.

如果mbstr是空指针,无效参数处理程序调用中所述,参数验证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 OverloadsFor more information, see Secure Template Overloads.

异常Exceptions

Mbsrtowcs函数是多线程安全,前提是当前线程中的函数不调用setlocale ,只要此函数正在执行和mbstate参数不是 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