Linux程序员手册 第3部分
更新日期： 2019-03-06

名称

mbrtowc-将多字节序列转换为宽字符

语法

#include <wchar.h>

size_t mbrtowc(wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);

说明

此函数的主要情况是s不为NULL且pwc不为NULL时。在这种情况下，mbrtowc()函数检查从s开始的多字节字符串中最多n个字节，提取下一个完整的多字节字符，将其转换为宽字符并将其存储在* pwc中。它更新移位状态* ps。如果转换后的宽字符不是Laq \ 0aq(空宽字符)，它将返回从s消耗的字节数。如果转换后的宽字符为Laq \ 0aq，则它将移位状态* ps重置为初始状态并返回0。

如果从s开头的n个字节不包含完整的多字节字符，则mbrtowc()返回(size_t)-2。即使多字节字符串包含冗余移位序列，即使n> = MB_CUR_MAX，也可能发生这种情况。

如果以s开头的多字节字符串在下一个完整字符之前包含无效的多字节序列，则mbrtowc()返回(size_t)-1，并将errno设置为EILSEQ。在这种情况下，对* ps的影响是不确定的。

另一种情况是当s不为NULL但pwc为NULL时。在这种情况下，mbrtowc()函数的行为如上所述，只是它不将转换后的宽字符存储在内存中。

第三种情况是当s为NULL时。在这种情况下，pwc和n被忽略。如果* ps表示的转换状态表示不完整的多字节字符转换，则mbrtowc()函数返回(size_t)-1，将errno设置为EILSEQ，并将* ps保留为未定义状态。否则，mbrtowc()函数会将* ps置于初始状态并返回0。

在上述所有情况下，如果ps为NULL，则将使用仅mbrtowc()函数已知的静态匿名状态。否则，* ps必须是有效的mbstate_t对象。可以通过将mbstate_t对象a调零将其初始化为初始状态，例如使用

memset(&a, 0, sizeof(a));

返回值

如果识别出非Laq \ 0aq宽字符，则mbrtowc()函数返回从s开始的多字节序列中解析的字节数。如果识别出Laq \ 0aq宽字符，则返回0。如果遇到无效的多字节序列，它将返回(size_t)-1，并将errno设置为EILSEQ。如果无法解析完整的多字节字符，则返回(size_t)-2，这意味着应增加n。

属性

有关本节中使用的术语的说明，请参见attribute(7)。

遵循规范

POSIX.1-2001，POSIX.1-2008，C99。

备注

mbrtowc()的行为取决于当前语言环境的LC_CTYPE类别。

另外参见

mbsinit(3)，mbsrtowcs(3)

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本，请访问https://www.kernel.org/doc/man-pages/。