iconv(3C)

NAME
     iconv - code conversion function

SYNOPSIS
     #include <iconv.h>

     size_t iconv(iconv_t cd, const char **inbuf, size_t *inbytesleft,
                  char **outbuf, size_t *outbytesleft);

DESCRIPTION
     The iconv() converts a string of characters from one codeset, in a input
     buffer, into a sequence of corresponding characters in another codeset in
     a output buffer.

     The cd is a conversion descriptor that was returned by the preceding
     iconv_open() function call which specifies the correct codeset converter.

     The inbuf points to a variable that points to the beginning of the input
     buffer that has the characters to be converted, and the variable pointed
     by inbuf is updated to point to the byte following the last byte
     successfully used in the conversion.  If the input buffer ends with an
     incomplete character or shift sequence, conversion stops after the
     previous successfully converted bytes.  If a sequence of input bytes does
     not form a valid character in the codeset, conversion stops after the
     previous successfully converted character.

     The inbytesleft indicates the number of bytes to the end of the buffer
     still to be converted and the value pointed to by inbytesleft is
     decremented to reflect the number of bytes still not converted in the
     input buffer.

     The outbuf points to a variable that points to the first available byte
     in the output buffer that contains the converted characters, and the
     variable pointed to by outbuf is updated to point to the byte following
     the last byte of converted output characters.  If the output buffer is
     not large enough to contain all the converted characters, conversion
     stops and the character that causes the overflow is not converted.

     The outbytesleft indicates the number of the free bytes to the end of the
     buffer and the value pointed to by outbytesleft is decremented to reflect
     the number of bytes still available in the output buffer.

     The iconv() function will fail under the following conditions and set
     errno to the suitable value.

     [EINVAL]

          Conversion stopped due to an incomplete character or shift sequence
          at the end of the input buffer.
     [EILSEQ]

          Conversion stopped due to an input byte that does not belong to the
          input codeset.

     [E2BIG]

          Conversion stopped because of shortage of space in the output
          buffer. The character in the input buffer that caused the overflow
          was not converted.

     [EBADF]

          The cd argument does not specify a valid open conversion descriptor.

     The iconv() function returns a value of 0 if all of characters in the
     input buffer is converted, and the value pointed to by inbytesleft will
     be 0.  The iconv() returns (size_t)-1 if an error occurs, and the value
     pointed to by inbytesleft will be non-zero. In such cases, errno is set
     to indicate the condition.


SEE ALSO
     iconv_open(3C) , iconv_close(3C)