Iconv (3)

Iconv (3) Linux programmer Manual
　　
Name
Iconv-complete character set Conversion
　　
Syntax
# Include
Size_t iconv (iconv_t CD,
Char ** inbuf, size_t * inbytesleft,
Char ** outbuf, size_t * outbytesleft );
　　
Description
　　
The parameter CD must be a conversion descriptor created by the iconv_open function.
　　
The main cases are when inbuf and * inbuf are not empty. In this case, the iconv function converts a multi-Character Sequence * inbuf to another multi-Character Sequence * outbuf. Starting from * inbuf, a maximum of * inbytesleft bytes will be read, and a maximum of * outbytesleft bytes will be written to * outbuf.
　　
The iconv function converts a multi-byte character at a time. Each time a multi-byte character is converted, * inbuf will automatically increase and * inbytesleft minus the number of converted bytes. Similarly, * outbuf and * outbytesleft increase and decrease the same values respectively. At the same time, it updates the CD status. The conversion will be stopped for the following four reasons:
　　
1. inbuf encounters an abnormal multi-Character Sequence. In this case, it sets errno to eilseq and returns (size_t) (-1 ). * Inbuf is at the beginning of the abnormal sequence.
　　
2. The input bytes are fully converted. For example, * inbytesleft has been reduced to 0. In this case, iconv returns the number of characters that cannot be converted during conversion.
　　
3. An incomplete multi-Character Sequence is encountered in the input and ended here. In this case, it sets the errno value to Val and returns (size_t) (-1 ). * Inbuf points to the starting point of an incomplete character sequence.
　　
4. The output buffer space is insufficient to accommodate characters that have been converted. In this case, it sets errno to e2big and returns (size_t) (-1 ).
　　
One difference is that when inbuf or * inbuf is empty, but both outbuf and * outbuf are not empty. At this time, the iconv function will try to set the CD state to the initial state and store the corresponding sequence in * outbuf. A maximum of * outbytesleft characters may be written. If the output buffer does not have enough space to store this reschedule sequence, errno is set to e2big and returns (size_t) (-1 ). In addition, it increases or decreases the values of * outbuft and * outbytesleft respectively by the number of written bytes.
　　
In the third case, when inbuf or * inbuf is empty and outbuf and * outbuf are empty. At this time, the iconv function sets CD to the status at the time of initialization.
　　
Return Value
The iconv function returns the number of converted characters that cannot be reversed. reversible conversion is not included. When an error occurs, it sets the errno value to (size_t) (-1 ).
　　
Error
The following error may occur:
E2big: * The outbuf space is insufficient.
Eilseq: the input contains an abnormal character sequence.
Einval: the input contains incomplete character sequences.
　　
Follow
Unix98
　　
Reference
Iconv_open (3), iconv_close (3)
　　
GNU 2001-11-15 iconv (3)