ICONV(3) | Library Functions Manual | ICONV(3) |
iconv_open
, iconv_close
,
iconv
—
#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, const char **
restrict src, size_t *
restrict srcleft, char **
restrict dst, size_t *
restrict dstleft);
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.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.
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 has always
used the const form. It was decided to reject the committee's regression and
become (technically) incompatible.
iconv
() is aborted due to the occurrence of some
error, the “invalid conversion” count mentioned above is
unfortunately lost.
June 8, 2016 | NetBSD 9.2 |