iconv -- Convert Characters to New Code Set

Format

#include <iconv.h>
size_t iconv(iconv_t cd, char **inbuf, size_t *inbytesleft,
             char **outbuf, size_t *outbytesleft);

Language Level: XPG4
iconv converts a sequence of characters in one encoded character set, in the array indirectly pointed to by inbuf, into a sequence of corresponding characters in another encoded character set. It stores the corresponding sequence in the array indirectly pointed to by outbuf. cd is the conversion descriptor returned from iconv_open that describes which codesets are used in the conversion.

For state-dependent encodings, the conversion descriptor cd is placed into its initial shift state by a call for which inbuf is a null pointer, or for which inbuf points to a null pointer. When iconv is called in this way, and if outbuf is not a null pointer or a null pointer to a null pointer, and outbytesleft points to a positive value, iconv will place, into the output buffer, the byte sequence to change the output buffer to its initial shift state. If the output buffer is not large enough to hold the entire reset sequence, iconv will fail and set errno to E2BIG. Subsequent calls with inbuf as other than a null pointer or a pointer to a null pointer cause the conversion to take place from the current state of the conversion descriptor.

inbuf points to a variable that points to the first character in the input buffer, and inbytesleft indicates the number of bytes to the end of the buffer. outbuf points to a variable that points to the first available byte in the output buffer, and outbytesleft indicates the number of available bytes to the end of the buffer.

As iconv converts the characters, it updates the variable pointed to by inbuf to point to the next byte in the input buffer, and updates the variable pointed to by outbuf to the byte following the last successfully converted character. It also decrements inbytesleft and outbytesleft to reflect the number of bytes of input remaining and the number of bytes still available for output, respectively. If the entire input string is converted, insize will be 0; if an error stops the conversion, insize will have a nonzero value.

Sharing a conversion descriptor in iconv across multiple threads may result in undefined behavior.

Return Value
iconv returns the number of nonidentical conversions performed. In a nonidentical conversion, there is no equivalent character image in the target code pages. A substitution is required and the return code counts the number of instances when this happens. The subsitution character is specified in the conversion table of the target code page, and is not always the same.

If the entire string in the input buffer is converted, inbytesleft points to 0. If the input conversion stops, inbytesleft points to nonzero and errno is set to indicate the condition that caused the conversion to stop. If an error occurs, iconv returns (size_t)-1, and sets errno to one of the following values:

Value Meaning
EILSEQ An input byte does not belong to the input codeset.
E2BIG outbuf is not large enough to hold the converted value.
EINVAL Incomplete character or shift sequence at the end of the input buffer.
EBADF cd is not a valid conversion descriptor.

If the input buffer equals NULL, iconv changes the conversion state to the single byte. No error message is generated.

Example



Locales and Localization


iconv_close -- Remove Conversion Descriptor
iconv_open -- Create Conversion Descriptor
setlocale -- Set Locale
<locale.h>