### 15.1 `iconv`, `iconv_open`, `iconv_close`—charset conversion routines ¶

Synopsis

    #include <iconv.h>
    iconv_t iconv_open (const char *to, const char *from);
    int iconv_close (iconv_t cd);
    size_t iconv (iconv_t cd, char **restrict inbuf,
        size_t *restrict inbytesleft,
        char **restrict outbuf,
        size_t *restrict outbytesleft);

    iconv_t _iconv_open_r (struct _reent *rptr,
        const char *to, const char *from);
    int _iconv_close_r (struct _reent *rptr, iconv_t cd);
    size_t _iconv_r (struct _reent *rptr,
        iconv_t cd, const char **inbuf,
        size_t *inbytesleft,
        char **outbuf, size_t *outbytesleft);

Description
The function `iconv` converts characters from in which are in one encoding to characters of another encoding, outputting them to out. The value inleft specifies the number of input bytes to convert whereas the value outleft specifies the size remaining in the out buffer. The conversion descriptor cd specifies the conversion being performed and is created via `iconv_open`.

An `iconv` conversion stops if: the input bytes are exhausted, the output buffer is full, an invalid input character sequence occurs, or the conversion specifier is invalid.

The function `iconv_open` is used to specify a conversion from one encoding: from to another: to. The result of the call is to create a conversion specifier that can be used with `iconv`.

The function `iconv_close` is used to close a conversion specifier after it is no longer needed.

The `_iconv_r`, `_iconv_open_r`, and `_iconv_close_r` functions are reentrant versions of `iconv`, `iconv_open`, and `iconv_close`, respectively. An additional reentrancy struct pointer: rptr is passed to properly set `errno`.

Returns
The `iconv` function returns the number of non-identical conversions performed. If an error occurs, (size_t)-1 is returned and `errno` is set appropriately. The values of inleft, in, out, and outleft are modified to indicate how much input was processed and how much output was created.

The `iconv_open` function returns either a valid conversion specifier or (iconv_t)-1 to indicate failure. If failure occurs, `errno` is set appropriately.

The `iconv_close` function returns 0 on success or -1 on failure. If failure occurs `errno` is set appropriately.

Portability
`iconv`, `iconv_open`, and `iconv_close` are non-ANSI and are specified by the Single Unix specification.

No supporting OS subroutine calls are required.