mbstowcs_s， _mbstowcs_s_l

项目
02/21/2013

将多字节字符序列转换为相应的宽字符序列。版本的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缓冲区中的单词。
[] inmbstr
地址序列中的空值终止的多字节字符。
[in] count
最大的存储中的宽字符数wcstr的缓冲区，不包括终止 null，或_TRUNCATE。
[in] locale
可用的区域设置。

返回值

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

错误条件	返回值和errno
wcstris NULL and sizeInWords > 0	EINVAL
mbstr 为 NULL	EINVAL
目标缓冲区太小，无法包含已转换的字符串（除非count是_TRUNCATE。请参阅下面的备注）	ERANGE
wcstris not NULL and sizeInWords == 0	EINVAL

如中所述，如果发生其中任一条件时，调用无效参数异常参数验证。如果允许执行继续，则函数返回一个错误代码，并设置errno表中所示。

备注

mbstowcs_s函数将指向的多字节字符的字符串转换mbstr所指向的缓冲区中存储的宽字符到wcstr。转换将继续为每个字符，直到满足以下条件之一：

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

目标字符串始终是以空值终止（甚至在的情况下出现的错误）。

如果count的特殊值_TRUNCATE，然后mbstowcs_s尽可能将字符串转换为适合目标缓冲区中，同时仍保留为空终止符）留出空间。

如果mbstowcs_s成功将转换的源字符串，它将大小放在宽字符的转换的字符串，包括空终止符）更改为*pReturnValue （提供pReturnValue不是NULL)。出现这种情况即使wcstr参数是NULL ，并提供了一种方法来确定所需的缓冲区大小。Note that if wcstr is NULL, count is ignored, and sizeInWords must be 0.

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

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