mbstowcs_s, _mbstowcs_s_l

项目
06/09/2015

将多字节字符序列转换为对应的宽字符序列。 mbstowcs、_mbstowcs_l 的一些版本提供安全增强功能（如 CRT 中的安全功能所述）。

errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count 
);
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count 
); // C++ only
template <size_t size>
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count,
   _locale_t locale
); // C++ only

参数

[out] pReturnValue
要转换的字符数。
[out] wcstr
结果的缓冲区地址转换成宽字符字符串。
[in] sizeInWords
wcstr 缓冲区大小(以字为单位)。
[in]mbstr
多字节字符序列的空终止字符的地址。
[in] count
wcstr 缓冲区中存储的宽字符的最大页数，不包括 null 终止符或 _TRUNCATE。
[in] locale
要使用的区域设置。

返回值

如果成功，则为零；如果失败，则为错误代码。

错误条件	返回值和errno
wcstr 是 NULL 和 sizeInWords > 0	EINVAL
mbstr 为 NULL	EINVAL
目标缓冲区因过小而无法包含转换的字符串。(除非 count 是 _TRUNCATE；请参见下面"备注")	ERANGE
wcstr 不是 NULL 和 sizeInWords == 0	EINVAL

如果任一错误状态发生，调用无效参数异常，如参数验证所述。如果允许继续执行，函数返回错误代码然后按照下表设置 errno。

备注

mbstowcs_s 函数将由mbstr 指向的缓冲区存储的多字节字符转换为 wcstr指向的缓冲区的宽字节字符。字符的转换将继续进行，直到与这些情况之一匹配：

遇到多字节字符null
遇到无效的多字节字符
在 wcstr 缓冲存储的宽字符数等于 count。

目标字符串始终为 null 终止 (即使发生错误)。

如果 count 是特殊值 _TRUNCATE，则当仍有 null 结束符的空间时，mbstowcs_s 将许多字符串整合到目标缓冲区。

如果 mbstowcs_s 成功转换了源字符串，它将转换字符串的宽字符的大小（包括空终止符）放入*pReturnValue。(提供的 pReturnValue 不是 NULL)。即使 wcstr 参数为 NULL, 并提供方法来确定需要的缓冲区大小，也会发生这个事件。请注意，如果 wcstr 为 NULL，将忽略 count，并且sizeInWords 必须为 0。

如果 mbstowcs_s 遇到无效的多字节字符，将0置于*pReturnValue，将目标缓冲区设为空字符串，errno 设置为 EILSEQ，并返回 EILSEQ。

如果由 mbstr 与 wcstr 指向的序列重叠，mbstowcs_s 行为是未定义的。