Linux程序员手册 第3部分
更新日期： 2017-09-15

名称

iconv-执行字符集转换

语法

#include <iconv.h>

size_t iconv(iconv_t cd,
             char **inbuf, size_t *inbytesleft,
             char **outbuf, size_t *outbytesleft);

说明

iconv()函数将一种字符编码的字符序列转换为另一种字符编码的字符序列。 cd参数是一个转换描述符，以前是通过调用iconv_open(3)创建的；转换描述符定义iconv()用于转换的字符编码。 inbuf参数是指向输入序列第一个字符的变量的地址。 inbytesleft指示该缓冲区中的字节数。 outbuf参数是变量的地址，该变量指向输出缓冲区中可用的第一个字节。 outbytesleft指示输出缓冲区中可用的字节数。

主要情况是inbuf不为NULL且* inbuf不为NULL的情况。在这种情况下，iconv()函数会将以* inbuf开头的多字节序列转换为以* outbuf开头的多字节序列。将读取最多* inbytes个从* inbuf开始的剩余字节。从* outbuf开始，最多将写入* outbytesleftbytes。

iconv()函数一次转换一个多字节字符，对于每次字符转换，它会将* inbuf和减量* inbytes增加转换后的输入字节数，然后将* outbuf和减量* outbytes保留转换后的输出字节数，并更新cd中包含的转换状态。如果输入的字符编码是有状态的，则iconv()函数还可以将输入字节序列转换为对转换状态的更新，而不会产生任何输出字节。这样的输入称为移位序列。转换可能由于以下四个原因而停止：

1.

输入中遇到无效的多字节序列。在这种情况下，它将errno设置为EILSEQ并返回(size_t)-1。 * inbuf指向无效的多字节序列的开头。

2.

输入的字节序列已完全转换，即* inbytesleft已降至0。在这种情况下，iconv()返回在此调用期间执行的不可逆转换的次数。

3.

输入中遇到不完整的多字节序列，输入字节序列在此之后终止。在这种情况下，它将errno设置为EINVAL并返回(size_t)-1。 * inbuf指向不完整的多字节序列的开头。

4.

输出缓冲区不再有空间容纳下一个转换的字符。在这种情况下，它将errno设置为E2BIG并返回(size_t)-1。

另一种情况是inbuf为NULL或* inbuf为NULL，但outbuf不为NULL和* outbuf不为NULL。在这种情况下，iconv()函数尝试将cd的转换状态设置为初始状态，并将相应的移位序列存储在* outbuf。从* outbuf开始，最多将写入* outbytesleftbytes。如果输出缓冲区没有更多空间可用于此复位序列，则会将errno设置为E2BIG并返回(size_t)-1。否则，它会将* outbuf递增，并将剩余的* outbytes递减所写入的字节数。

第三种情况是inbuf为NULL或* inbuf为NULL，而outbuf为NULL或* outbuf为NULL。在这种情况下，iconv()函数将cd的转换状态设置为初始状态。

返回值

iconv()函数返回此调用过程中以不可逆方式转换的字符数。可逆转换不计算在内。如果发生错误，它将设置errno并返回(size_t)-1。

错误说明

除其他外，可能发生以下错误：

E2BIG

* outbuf没有足够的空间。

EILSEQ

输入中遇到无效的多字节序列。

EINVAL

输入中遇到了不完整的多字节序列。

版本

从2.1版开始，此功能在glibc中可用。

属性

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

iconv()函数是MT安全的，只要调用方安排cd参数上的互斥即可。

遵循规范

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

备注

在对iconv()的每个调用系列中，最后一个应该是inbuf或* inbuf等于NULL的调用，以便清除任何部分转换的输入。

尽管inbuf和outbuf的类型为char **，但这并不意味着它们指向的对象可以解释为C字符串或字符数组：字符字节序列的解释由转换函数内部处理。在某些编码中，零字节可能是多字节字符的有效部分。

iconv()的调用者必须确保传递给函数的指针适合于访问适当字符集中的字符。这包括确保在对对齐有严格限制的平台上正确对齐。

另外参见

iconv_close(3)，iconv_open(3)，iconvconfig(8)

出版信息

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