iconv(3)

ICONV(3) Linux程序员手册 
　　
　　名称 
　　iconv – 完成字符集转换 
　　
　　语法 
　　 #include 
　　 size_t iconv(iconv_t cd, 
　　 char **inbuf, size_t *inbytesleft, 
　　 char **outbuf, size_t *outbytesleft); 
　　
　　描述 
　　
　　参数cd必须是由iconv_open函数创建的一个转换描述符。 
　　
　　主要的案例是inbuf和*inbuf非空的时候。在这种情况下，iconv函数转换一个多字符序列*inbuf到另一个多字符序列*outbuf。从*inbuf开始，会有最多*inbytesleft个字节被读取，并且会有最多*outbytesleft个字节被写入*outbuf。 
　　
　　iconv函数一次转换一个多字节字符，每转换一个多字节字符，*inbuf会自增并且*inbytesleft减去已经转换的字节数。同样，*outbuf和*outbytesleft也分别增加和减少相同的数值。同时它会更新cd的状态。转换工作会因为下面的四个原因而停止： 
　　
　　1. Inbuf遇到不正常的多字符序列。在这种情况下，它将errno设置为EILSEQ并且返回（size_t）(-1)。*inbuf处于不正常序列的开始处。 
　　
　　2. 输入字节完全被转换，比如，*inbytesleft已经减少到0。在这种情况下，iconv返回转换期间不可转换字符的数量。 
　　
　　3. 在输入中遇到不完全的多字符序列，并且终止于此。在这种情况下，它会设置errno的值为EINVAL并且返回(size_t)(-1)。*inbuf指向不完全的字符序列开始的地方。 
　　
　　4. 输出缓冲区空间不足，无法容纳已经转换好的字符。这种情况下，它设置errno值为E2BIG并且返回(size_t)(-1)。 
　　
　　一种不同的情况是，当inbuf或*inbuf为空，但是outbuf和*outbuf均不为空的时候。这时，iconv函数会试图将cd的状态设置为初始状态并且在*outbuf中存储相应的序列。最多有*outbytesleft个字符可能被写入。如果输出缓冲区没有足够的空间来存储这个重新安排的序列，errno会被设置为E2BIG并且返回(size_t)(-1)。另外，它会用写入字节的数量来分别增加和减少*outbuft和*outbytesleft的值。 
　　
　　第三种情况是，当inbuf或*inbuf为空，并且outbuf和*outbuf也为空的时候。这时，iconv函数会设置cd为刚初始化时的状态。 
　　
　　返回值 
　　 iconv函数返回转换了的，不能再逆向转换的字符的个数；可逆的转换不会计算在内。发生错误的时候，它设置errno的值为(size_t)(-1)。 
　　
　　错误 
　　下面的错误可能会发生： 
　　 E2BIG：*outbuf空间不足。 
　　 EILSEQ：输入中含有不正常的字符序列。 
　　 EINVAL：输入中含有不完全的字符序列。 
　　
　　遵照 
　　 UNIX98 
　　
　　参考 
　　 iconv_open(3), iconv_close(3) 
　　
　　GNU 2001-11-15 ICONV(3)