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.