MBSNRTOWCS - Linux手册页

时间:2019-08-20 18:00:51  来源:igfitidea点击:

Linux程序员手册 第3部分
更新日期: 2020-06-09

名称

mbsnrtowcs-将多字节字符串转换为宽字符字符串

语法

#include <wchar.h>

size_t mbsnrtowcs(wchar_t *dest, const char **src,
                  size_t nms, size_t len, mbstate_t *ps);

glibc的功能测试宏要求(请参阅feature_test_macros(7)):

mbsnrtowcs():

Since glibc 2.10:
_POSIX_C_SOURCE>= 200809L
Before glibc 2.10:
_GNU_SOURCE

说明

mbsnrtowcs()函数类似于mbsrtowcs(3)函数,除了要转换的字节数(从* src开始)最多为nms字节。

如果dest不为NULL,则mbsnrtowcs()函数最多将nms字节从多字节字符串* src转换为以dest开始的宽字符字符串。最多len个宽字符被写入dest。移位状态* ps被更新。只要反复调用mbrtowc(dest,* src,n,ps)(其中n是某个正数)即可有效地执行转换,只要此调用成功,然后将dest递增1,* src递增所消耗的字节数即可。转换可能由于以下三个原因而停止:

1.
遇到无效的多字节序列。在这种情况下,* src指向无效的多字节序列,返回(size_t)-1,并且errno设置为EILSEQ。
2.
nms限制会强制停止,或者在dest中存储了len个非Laq \ 0aq宽字符。在这种情况下,* src指向要转换的下一个多字节序列,并返回写入dest的宽字符数。
3.
多字节字符串已被完全转换,包括终止的空宽字符(aq \ 0aq)(其副作用是使* ps返回初始状态)。在这种情况下,* src设置为NULL,并且返回写入dest的宽字符数(不包括终止的空宽字符)。

根据POSIX.1,如果输入缓冲区以不完整的字符结尾,则不确定转换是在上一个字符(如果有)的结尾还是在输入缓冲区的结尾处停止。 glibc实现采用以前的行为。

如果dest为NULL,则len被忽略,并且转换按上述方式进行,只是转换后的宽字符不会写出到内存中,并且不存在目标长度限制。

在上述两种情况下,如果ps为NULL,则将使用仅mbsnrtowcs()函数已知的静态匿名状态。

程序员必须确保至少有至少len个宽字符可用的空间。

返回值

mbsnrtowcs()函数返回构成宽字符字符串的转换部分的宽字符数,不包括终止的空宽字符。如果遇到无效的多字节序列,则返回(size_t)-1,并将errno设置为EILSEQ。

属性

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

InterfaceAttributeValue
mbsnrtowcs()Thread safetyMT-Unsafe race:mbsnrtowcs/!ps

遵循规范

POSIX.1-2008。

备注

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

作为ps传递NULL不是多线程安全的。

另外参见

iconv(3),mbrtowc(3),mbsinit(3),mbsrtowcs(3)

出版信息

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