mbsrtowcs_s

将当前区域设置中的多字节字符字符串转换为宽字符字符串表示形式。 这是 mbsrtowcs 版本，具有 CRT 中的安全性功能中所述的安全性增强功能。

语法

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

参数

pReturnValue
要转换的字符数。

wcstr
用于存储转换所生成的宽字符字符串的缓冲区地址。

sizeInWords
wcstr 的大小（宽字符）（以单词为单位）。

mbstr
指向要转换的多字节字符字符串位置的间接指针。

count
要存储在 wcstr 缓冲区中的宽字符的最大数量，不包括终止 null 或 _TRUNCATE。

mbstate
指向 mbstate_t 转换状态对象的指针。 如果此值为 null 指针，则使用静态内部转换状态对象。 由于内部 mbstate_t 对象不是线程安全的，建议始终传递你自己的 mbstate 参数。

返回值

如果转换成功则返回零；如果失败则返回错误代码。

添加状态	返回值和 errno
wcstr 为空指针且 sizeInWords> 0	EINVAL
mbstr 为 null 指针	EINVAL
mbstr 间接指向的字符串包含一个对当前区域设置无效的多字节序列。	EILSEQ
目标缓冲区过小，无法包含转换后的字符串（除非 count 是 _TRUNCATE；有关详细信息，请参阅备注）	ERANGE

如果发生这些情况中的任何一个，都会调用无效的参数异常，如参数验证中所述。 如果允许执行继续，函数将返回错误代码并按表中所示设置 errno。

备注

mbsrtowcs_s 函数通过使用 mbstr 中包含的转换状态，将 wcstr 间接指向的多字节字符的字符串转换为存储在 mbstate 指向的缓冲区中的宽字符。 在满足以下条件之一前，该转换将一直对每个字符执行：

• 遇到一个多字节空字符

• 遇到一个无效的多字节字符

• 存储在 wcstr 缓冲区中的宽字符数等于 count。

目标字符串 wcstr 始终以 null 值结束，即使在发生错误的情况下也是如此，除非 wcstr 为空指针。

如果 count 是特殊值 _TRUNCATE，则 mbsrtowcs_s 会根据目标缓冲区的容量尽量多地转换字符串，同时仍然为 null 结束符留下空间。

如果 mbsrtowcs_s 成功转换了源字符串，则它会将经转换的字符串和 null 终止符的宽字符大小置于 *pReturnValue 中，前提是 pReturnValue 不是空指针。 即使 wcstr 参数为空指针，也会计算该大小，从而确定所需的缓冲区大小。 如果 wcstr 为空指针，则忽略 count。

如果 wcstr 不是空指针，则在转换因到达终止空字符而停止时，mbstr 指向的指针对象将被分配一个空指针。 否则，它将被分配紧跟已转换的最后一个多字节字符的地址（如有）。 它使后续函数调用能够在此调用停止的位置重启转换。

如果 mbstate 为 null 指针，则将使用库内部 mbstate_t 转换状态静态对象。 由于此内部静态对象不是线程安全的，建议传递你自己的 mbstate 值。

如果 mbsrtowcs_s 遇到在当前区域设置中无效的多字节字符，它会将 -1 放到 *pReturnValue 中，将目标缓冲区 wcstr 设置为空字符串，将 errno 设置为 EILSEQ，并返回 EILSEQ。

如果 mbstr 和 wcstr 指向的序列重叠，则 mbsrtowcs_s 的行为没有定义。 mbsrtowcs_s 受到当前区域设置的 LC_TYPE 类别的影响。

重要

确保 wcstr 和 mbstr 未重叠，并且 count 正确反映了要转换的多字节字符的数量。

mbsrtowcs_s 函数的可重启性不同于 mbstowcs_s、_mbstowcs_s_l。 转换状态存储在 mbstate 中，以便后续调用相同的或其他可重启函数。 混合使用可重启函数和不可重启函数时，结果不确定。 例如，如果使用 mbsrtowcs_s（而非 mbstowcs_s）的后续调用，则应用程序应使用 mbsrlen，而不是 mbslen。

在 C++ 中，模板重载简化了这些函数的使用。重载可以自动推导出缓冲区长度（不再需要指定大小自变量），并且它们可以通过使用更新、更安全的对应函数来自动替换旧的、不安全的函数。 有关详细信息，请参阅安全模板重载。

默认情况下，此函数的全局状态范围限定为应用程序。 要更改此行为，请参阅 CRT 中的全局状态。

异常

只要 mbsrtowcs_s 函数正在执行且 mbstate 参数不是空指针，当前线程中的函数都不调用 setlocale 时，此函数就是多线程安全的。

要求

例程	必需的标头
mbsrtowcs_s	<wchar.h>

另请参阅

数据转换
区域设置
多字节字符序列的解释
mbrtowc
mbtowc、_mbtowc_l
mbstowcs_s、_mbstowcs_s_l
mbsinit