Converts characters coded in one codeset to characters coded in
    another codeset.

    Format

      #include  <iconv.h>

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

1  –  Arguments

 cd

    A conversion descriptor. This is returned by a successful call to
    iconv_open.

 inbuf

    A pointer to a variable that points to the first character in the
    input buffer.

 inbytesleft

    Initially, this argument is a pointer to a variable that
    indicates the number of bytes to the end of the input buffer
    (inbuf). When the conversion is completed, the variable indicates
    the number of bytes in inbuf not converted.

 outbuf

    A pointer to a variable that points to the first available byte
    in the output buffer. The output buffer contains the converted
    characters.

 outbytesleft

    Initially, this argument is a pointer to a variable that
    indicates the number of bytes to the end of the output buffer
    (outbuf). When the conversion is completed, the variable
    indicates the number of bytes left in outbuf.

2  –  Description

    The iconv function converts characters in the buffer pointed
    to by inbuf to characters in another code set. The resulting
    characters are stored in the buffer pointed to by outbuf. The
    conversion type is specified by the conversion descriptor cd.
    This descriptor is returned from a successful call to iconv_open.

    If an invalid character is found in the input buffer, the
    conversion stops after the last successful conversion. The
    variable pointed to by inbytesleft is updated to reflect the
    number of bytes in the input buffer that are not converted. The
    variable pointed to by outbytesleft is updated to reflect the
    number of bytes remaining in the output buffer.

3  –  Return Values

    x                  Number of nonidentical conversions performed.
                       Indicates successful conversion. In most
                       cases, 0 is returned.
    (size_t) -1        Indicates an error condition. The function
                       sets errno to one of the following:

                       o  EBADF - The cd argument is not a valid
                          conversion descriptor.

                       o  EILSEQ - The conversion stops when an
                          invalid character detected.

                       o  E2BIG - The conversion stops because of
                          insufficient space in the output buffer.

                       o  EINVAL - The conversion stops because of
                          an incomplete character at the end of the
                          input buffer.