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.