The
iconv_open() function opens a converter from the codeset
srcname to the codeset
dstname and returns its descriptor.
The
iconv_close() function closes the specified converter
cd.
The
iconv() function converts the string in the buffer
*src of length
*srcleft bytes and stores the converted string in the buffer
*dst of size
*dstleft bytes. After calling
iconv(), the values pointed to by
src,
srcleft,
dst, and
dstleft are updated as follows:
*src
Pointer to the byte just after the last character fetched.
*srcleft
Number of remaining bytes in the source buffer.
*dst
Pointer to the byte just after the last character stored.
*dstleft
Number of remainder bytes in the destination buffer.
If the string pointed to by
*src contains a byte sequence which is not a valid character in the source codeset, the conversion stops just after the last successful conversion. If the output buffer is too small to store the converted character, the conversion also stops in the same way. In these cases, the values pointed to by
src,
srcleft,
dst, and
dstleft are updated to the state just after the last successful conversion.
If the string pointed to by
*src contains a character which is valid under the source codeset but can not be converted to the destination codeset, the character is replaced by an “invalid character” which depends on the destination codeset, e.g., ‘?', and the conversion is continued.
iconv() returns the number of such “invalid conversions”.
If the source and/or destination codesets are stateful,
iconv() places these into their initial state. There are two special cases of
iconv():
1.
If both dst and *dst are non-NULL, iconv() stores the shift sequence for the destination switching to the initial state in the buffer pointed to by *dst. The buffer size is specified by the value pointed to by dstleft as above. iconv() will fail if the buffer is too small to store the shift sequence.
2.
On the other hand, dst or *dst may be NULL. In this case, the shift sequence for the destination switching to the initial state is discarded.