NAME
iconv_open,
iconv_close,
iconv —
codeset conversion
functions
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#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);
DESCRIPTION
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:
-
-
- *src
- Pointer to the byte just after the last character
fetched.
-
-
- *srcleft
- Number of remaining bytes in the source buffer.
-
-
- *dst
- Pointer to the byte just after the last character
stored.
-
-
- *dstleft
- Number of remainder bytes in the destination buffer.
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.
- If both dst and
*dst are
non-
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.
- On the other hand, dst or
*dst may be
NULL
. In this
case, the shift sequence for the destination switching to the initial
state is discarded.
RETURN VALUES
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.
ERRORS
The
iconv_open() function may cause an error in the following
cases:
-
-
- [
EINVAL
]
- There is no converter specified by
srcname and dstname.
-
-
- [
ENOMEM
]
- Memory is exhausted.
The
iconv_close() function may cause an error in the following
case:
-
-
- [
EBADF
]
- The conversion descriptor specified by
cd is invalid.
The
iconv() function may cause an error in the following
cases:
-
-
- [
E2BIG
]
- The output buffer pointed to by *dst
is too small to store the result string.
-
-
- [
EBADF
]
- The conversion descriptor specified by
cd is invalid.
-
-
- [
EILSEQ
]
- The string pointed to by *src
contains a byte sequence which does not describe a valid character of the
source codeset.
-
-
- [
EINVAL
]
- The string pointed to by *src
terminates with an incomplete character or shift sequence.
SEE ALSO
iconv(1)
STANDARDS
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.
BUGS
If
iconv() is aborted due to the occurrence of some error, the
“invalid conversion” count mentioned above is unfortunately
lost.