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是未定义的。

安全说明
请确保wcstr和mbstr不重叠，和count正确反映出的所有多字节字符转换。

mbstowcs_s使用当前区域设置的区域设置相关的任何行为； _mbstowcs_s_l不同之处在于它使用的区域设置，而是传入的是相同的。有关更多信息，请参见区域设置。

在 C++ 中，使用这些函数是通过简化模板重载。重载可以自动推理缓冲区的长度（无需指定一个大小参数），它们可以自动使用较新的安全与对应替换较旧、不安全的函数。有关更多信息，请参见安全模板重载。

要求

例程	所需的页眉
mbstowcs_s	<stdlib.h>
_mbstowcs_s_l	<stdlib.h>

其他兼容性信息，请参阅兼容性的介绍。

.NET Framework 等效项

不适用。若要调用标准的 C 函数，使用PInvoke。有关详细信息，请参阅平台调用示例。

请参见

参考

_mbclen， mblen， _mblen_l

mbtowc， _mbtowc_l

wcstombs， _wcstombs_l

wctomb， _wctomb_l

mbstowcs_s， _mbstowcs_s_l

参数

返回值

备注

要求

.NET Framework 等效项

请参见

参考

其他资源