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.
![]()
iconv_close -- Remove Conversion
Descriptor
iconv_open -- Create Conversion
Descriptor
setlocale -- Set Locale
<locale.h>