mbsrtowcs_smbsrtowcs_s

将当前区域设置中的多字节字符字符串转换为宽字符字符串表示形式。Convert a multibyte character string in the current locale to its wide character string representation. 这是 mbsrtowcs 版本,具有 CRT 中的安全功能中所述的安全增强功能。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 或_TRUNCATEThe 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对象不是线程安全,我们建议始终传递你自己mbstate参数。Because the internal mbstate_t object is not thread-safe, we recommend that you always pass your own mbstate parameter.

返回值Return Value

如果转换成功则返回零;如果失败则返回错误代码。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.

备注Remarks

Mbsrtowcs_s函数将转换的间接指向的多字节字符字符串mbstr存储指向的缓冲区中的宽字符wcstr,也可由使用中包含的转换状态mbstateThe 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:

  • 遇到一个多字节空字符A multibyte null character is encountered

  • 遇到一个无效的多字节字符An invalid multibyte character is encountered

  • 存储中的宽字符数wcstr缓冲等于计数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.

如果mbstate是 null 指针,内部库mbstate_t使用转换状态静态对象。If mbstate is a null pointer, the library internal mbstate_t conversion state static object is used. 由于此内部静态对象不是线程安全的因此我们建议传递你自己mbstate值。Because this internal static object is not thread-safe, we recommend that you pass your own mbstate value.

如果mbsrtowcs_s遇到在当前的区域中,不是有效的多字节字符它将为-1 放在 *pReturnValue,设置目标缓冲区wcstr为空字符串,将设置errnoEILSEQ,并返回EILSEQIf 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. 转换状态存储在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_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 OverloadsFor more information, see Secure Template Overloads.

异常Exceptions

Mbsrtowcs_s函数是多线程安全,如果当前线程调用中的函数不setlocale ,只要此函数正在执行和mbstate自变量是不是 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