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
参数
[out] pReturnValue
转换后的字符数。[out] wcstr
缓冲区地址发生的转换过宽字符字符串。[out] sizeInWords
wcstr 的大小在运行 (宽字符)。[in] mbstr
指向要转换的多字节字符字符串的位置。[in] count
存储的宽的最大字符数在 wcstr 缓冲区,不包括终止 null 或 _TRUNCATE。[in] mbstate
为 mbstate_t 转换状态对象的指针。
返回值
零,如果成功,则失败的错误代码。
错误状态 |
返回值和 errno |
---|---|
wcstr 是 NULL 和 sizeInWords AMP_GT 0 |
EINVAL |
mbstr 为 NULL |
EINVAL |
(除非 count 是 _TRUNCATE,目标缓冲区因过小而无法包含被转换的字符串;请参见下面的 " 备注 ") |
ERANGE |
如果这些条件中的任何一个结果,无效参数异常调用 参数验证 如中所述。 如果执行允许继续,该函数返回错误代码并如下表所示设置 errno 。
备注
mbsrtowcs_s 函数多字节字符字符串 mbstr 点的转换为缓冲区存储的宽字符指向由 wcstr,在 mbstate包含的转换状态。 转换为每个字符将继续,直到上述任一条件匹配:
多字节 null 字符遇到
无效的多字节字符遇到
在 wcstr 缓冲区存储的宽字符数相等 count。
目标字符串始终以 null 终止 (即使在错误)。
如果 count 为特殊值 _TRUNCATE,则 mbsrtowcs_s 转换相同多个字符串与将放入目标缓冲区,那么,当仍 null 结束符时空间。
如果 mbsrtowcs_s 成功转换源字符串,它位于已转换的字符串的宽字符的范围,包括 null 结束符,以 *pReturnValue (提供的 pReturnValue 不是 NULL)。 发生这种情况,即使 wcstr 参数是 NULL 并提供用于确定所需的缓冲区大小。 请注意,如果 wcstr 是 NULL, count 被忽略。
如果 mbstate 是 NULL,使用内部 mbstate_t 转换状态。
如果 mbsrtowcs_s 遇到无效的多字节字符,它在 *pReturnValue放置 -1,设置目标缓冲区设置为空字符串,设置 errno 到 EILSEQ,并返回 EILSEQ。
如果顺序指向由 mbstr 和 wcstr 重叠, mbsrtowcs_s 行为不确定。 mbsrtowcs_s 受当前区域设置的 LC_TYPE 类别的影响。
安全说明 |
---|
确保 wcstr 和 mbstr 重叠,并且, count 准确反映多字节字符数转换。 |
mbsrtowcs_s 功能与 mbstowcs_s, _mbstowcs_s_l 不同由其 restartability。 转换状态中的 mbstate 存储的后续调用相同或其他可重新启动的功能。 ,混合使用可重新启动和 nonrestartable 函数时,结果是未定义的。 例如,应用程序将使用 mbsrlen 而不是 mbslen,因此,如果以后对 mbsrtowcs_s 使用了而不是 mbstowcs_s.
在 C++ 中,使用此函数由模板重载简化;重载可推断缓冲区长度 (自动不再需要指定范围参数),并且还可以用以较新,安全重复自动替换旧,不安全的功能。 有关更多信息,请参见 安全模板重载。
异常
mbsrtowcs 功能是多线程安全性,只要在当前线程的函数不调用 setlocale ,则此函数执行时,并 mbstate 为空。
.NET Framework 等效项
不适用。若要调用标准 C 函数,请使用 PInvoke。有关更多信息,请参见 平台调用示例。
要求
实例 |
必需的头 |
---|---|
mbsrtowcs |
wchar.h |