| ICONV(3) | Library Functions Manual | ICONV(3) |
iconv_open,
iconv_close, iconv —
codeset conversion functions
Standard C Library (libc, -lc)
#include
<iconv.h>
iconv_t
iconv_open(const
char *dstname, const char
*srcname);
int
iconv_close(iconv_t
cd);
size_t
iconv(iconv_t
cd, char ** restrict
src, size_t * restrict
srcleft, char ** restrict
dst, size_t * restrict
dstleft);
The
iconv_open()
function opens a converter from the codeset srcname to
the codeset dstname and returns its descriptor.
The
iconv_close()
function closes the specified converter cd.
The
iconv()
function converts the string in the buffer *src of
length *srcleft bytes and stores the converted string
in the buffer *dst of size
*dstleft bytes. After calling
iconv(), the values pointed to by
src, srcleft,
dst, and dstleft are updated as
follows:
If the string pointed to by *src contains a byte sequence which is not a valid character in the source codeset, the conversion stops just after the last successful conversion. If the output buffer is too small to store the converted character, the conversion also stops in the same way. In these cases, the values pointed to by src, srcleft, dst, and dstleft are updated to the state just after the last successful conversion.
If the string pointed to by
*src contains a character which is valid under the
source codeset but can not be converted to the destination codeset, the
character is replaced by an “invalid character” which depends
on the destination codeset, e.g., ‘?’, and the conversion is
continued.
iconv()
returns the number of such “invalid conversions”.
If src or
*src is NULL and the source
and/or destination codesets are stateful,
iconv()
places these into their initial state.
NULL,
iconv() stores the shift sequence for the
destination switching to the initial state in the buffer pointed to by
*dst. The buffer size is specified by the value
pointed to by dstleft as above.
iconv() will fail if the buffer is too small to
store the shift sequence.NULL. In this case, the shift sequence for
the destination switching to the initial state is discarded.Upon successful completion of
iconv_open(), it returns a conversion descriptor.
Otherwise, iconv_open() returns (iconv_t)-1 and sets
errno to indicate the error.
Upon successful completion of
iconv_close(), it returns 0. Otherwise,
iconv_close() returns -1 and sets errno to indicate
the error.
Upon successful completion of iconv(), it
returns the number of “invalid” conversions. Otherwise,
iconv() returns (size_t)-1 and sets errno to
indicate the error.
The iconv_open() function may cause an
error in the following cases:
The iconv_close() function may cause an
error in the following case:
EBADF]The iconv() function may cause an error in
the following cases:
E2BIG]EBADF]EILSEQ]EINVAL]iconv_open(),
iconv_close(), and iconv()
conform to IEEE Std 1003.1-2001
(“POSIX.1”).
Historically, the definition of iconv has
not been consistent across operating systems. This is due to an unfortunate
historical mistake, documented in
this
e-mail. The standards page for the header file
<iconv.h> defined the second
argument of iconv() as char
**, but the standards page for the iconv()
implementation defined it as const char **. The
standards committee later chose to change the function definition to follow
the header file definition (without const), even though the version with
const is arguably more correct. NetBSD used
initially the const form. It was decided to reject the committee's
regression and become (technically) incompatible.
This decision was changed in NetBSD 10 and
the iconv() prototype was synchronized with the
standard.
If iconv() is aborted due to the
occurrence of some error, the “invalid conversion” count
mentioned above is unfortunately lost.
| October 24, 2019 | NetBSD 11.0 |