ICONV(3)

ICONV(3) | Library Functions Manual | ICONV(3)

# 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, 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.

1. 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.
2. 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 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.

# BUGS

If `iconv`() is aborted due to the occurrence of some error, the “invalid conversion” count mentioned above is unfortunately lost.

October 24, 2019 | NetBSD 10.1