iconv

Converts an array of characters from one codeset to another

Library:LibC
Classification:POSIX
Service:Environment Variable

Syntax

  #include <iconv.h> 
   
  size_t  iconv (
     iconv_t   cd,
     char    **inbuf,
     size_t   *inbytesleft,
     char    **outbuf,
     size_t   *outbytesleft);

Parameters

cd

(IN) Specifies the codeset to use for the conversion. See iconv_open.

inbuf

(IN) Points to a pointer to the array of characters to convert.

inbytesleft

(IN/OUT) Points to a location holding the number of bytes from the byte, pointed to by the inbuf parameter, to the end of the buffer. After the call, the length pointed at is modified to indicate the next character in inbuf that has not yet been converted. See Remarks.

outbuf

(OUT) Points to a pointer to the array of converted characters.

outbytesleft

(IN/OUT) Points to a location holding the number of bytes available until the end of the buffer. After the call, the length pointed at is modified to indicate the amount of room still free in outbuf after all possible characters from inbuf have been converted.

Return Values

If successful in converting all the characters, returns the number of discrete (non-identical) translations made and sets 0 in the location pointed to by inbytesleft. This return value is the number of characters appearing in the final string. If an error occurs, returns -1 and sets errno to one of the following:

Decimal

Constant

Description

2

E2BIG

The conversion stopped because the output buffer is too small to hold all the characters.

4

EBADF

The cd parameter is invalid.

9

EINVAL

Input conversion stopped due to an incomplete character or shift sequence at the end of the input buffer.

101

EILSEQ

The conversion stopped because an input character, which does not belong to the input codeset, was found in the character array.

Remarks

The conversion stops if any of the following conditions occur:

  • A sequence of input bytes does not form a valid character in the input codeset.

  • The input buffer ends with an incomplete character or shift sequence.

  • The output buffer is not large enough to hold the entire converted input.

When any of these conditions occur, the iconv function returns the following values in its parameters:

  • The inbuf parameter returns a pointer to the byte following the last byte successfully converted.

  • The inbytesleft parameter returns the number of bytes that still need to be converted.

  • The outbuf parameter returns a pointer to the byte following the last byte of converted data.

  • The outbytesleft parameter returns a pointer to the number of bytes still available in the output buffer.

If the problem is E2BIG, you can have the conversion continue from the point it stopped by calling iconv with the returned parameters values.

See Also