August 1, 2004 ICONV 3

### NAME

iconv_open, iconv_close, iconv - codeset conversion functions

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```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''.

There are two special cases of iconv(``):

src == NULL || *src == NULL
  If 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:

[```ENOMEM`]
  Memory is exhausted.

[```EINVAL`]
  There is no converter specified by ```srcname` and ```dstname`.

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:

[```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.

[```E2BIG`]
  The output buffer pointed to by ```*dst` is too small to store the result string.

[```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'') .

### BUGS

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