iconv(S)

iconv_open, iconv_close, iconv -- convert characters from one codeset into another

Syntax

cc . . . -lc

#include <iconv.h>

iconv_t iconv_open (const char *tocode, const char *fromcode);

int     iconv_close(iconv_t cd);

size_t  iconv      (iconv_t cd, const char **inbuf, size_t *inbytesleft,
	            char **outbuf, size_t *outbytesleft);

Description

iconv_open(S) returns a conversion descriptor to be used later by iconv(S). This conversion descriptor remains valid in the process until it is closed by the process. To be portable, applications must assume that a call to any one of the exec(S) routines makes a conversion descriptor invalid.

iconv_close(S) closes the conversion descriptor and frees resources allocated by iconv_open( ) for the conversion descriptor.

iconv(S) converts character sequence from the codeset specified by the string fromcode to the codeset specified by the string tocode, in the manner described by this conversion descriptor. For more information on settings of fromcode and tocode, and their permitted combinations, see the description of the command iconv(C).

The sequence of characters to be converted is stored in the array pointed to by inbuf; the converted sequence of corresponding characters is put into an array pointed to by outbuf. The number of bytes still to be converted is *inbytesleft, which is initialized to the total number of bytes in the input buffer; the number of available bytes to the end of the output buffer is *outbytesleft, which is initialized to the size of the output buffer.

After each call to iconv( ), *inbuf is pointed to the byte following the last byte successfully used in the conversion and *inbytesleft is decremented to reflect the number of bytes still to be converted; *outbuf is pointed to the byte following the last byte of successfully converted output data and *outbytesleft is also decremented accordingly.

The conversion stops after the last successfully converted character if any of the following error conditions is encountered:

a sequence of input bytes is not a valid character in the codeset fromcode,
the input buffer ends with an incomplete character or shift sequence,

output buffer is not big enough for the entire converted string.

If a character in the input buffer is legal in the input codeset but does not have a counterpart in the target codeset, iconv( ) sets errno to [EILSEQ] and returns -1. As an SCO OpenServer specific feature, this input character can also be ignored (i.e., be skipped) by setting the flag _ICONV_DELETE in the conversion descriptor as:

   cd = iconv_open (....);
   cd->__state |= _ICONV_DELETE;  /* SCO SPECIFIC */

As another SCO OpenServer specific feature, one may choose how to process the ending character(s) in the input buffer if the character(s) may be interpreted both as complete and incomplete. For example, if ``a'' is at the end of the input buffer, and mappings such as:

    'a'   'd'
    'ab'  'e'

both exist, one will need to decide whether to

convert this ending ``a'' to ``d'', or
leave it un-converted and allow more characters to be appended to the input buffer to remove this ambiguity.

The default behavior, as if the flag _ICONV_COMP is set as in:

   cd->__state |= _ICONV_COMP;    /* SCO SPECIFIC */

after cd is opened, is to treat the ending character(s) as complete and perform the conversion. However, this flag should usually be set at the absolute end of translation of a chunk of text, for example, at the end of a file where no more data are expected.

If the flag is set differently as in

   cd->__state &= ~_ICONV_COMP;   /* SCO SPECIFIC */

the ending character(s) will be treated as incomplete and iconv( ) will not convert the character(s). Instead, it will then return -1 and set errno to [EINVAL]. This flag would be useful if more characters are expected to be available to remove the ambiguity.

Return values

Upon successful completion, iconv( ) returns the number of non-identical conversions performed (not number of characters converted). If the entire string pointed to by inbuf is converted successfully, *inbytesleft is zero. If only partial conversion can be performed due to any of the conditions stated above, *inbytesleft will be positive and errno is set.

If an error occurs, iconv( ) returns (size_t)-1 and sets errno to indicate the error.

Upon successful completion, iconv_open( ) returns a conversion descriptor to be used by iconv( ). Otherwise, (iconv_t)-1 is returned and errno is set.

Upon successful completion, iconv_close( ) returns zero. Otherwise, -1 is returned and errno is set.

Diagnostics

iconv( ) will fail if one or more of the following is true:

[EILSEQ]: Input byte does not belong to input code set or does not have a counterpart in the target code set, and the conversion stopped.
[E2BIG]: Output buffer is not big enough for the entire converted string and the conversion stopped.
[EINVAL]: The character or shift sequence at the end of the input buffer is not complete and the conversion stopped.

iconv( ) and iconv_close( ) may fail if the following is true:

[EBADF]: Invalid conversion descriptor is used.

iconv_open( ) may fail if any one of the following is true:

[EMFILE]: The calling process already has {OPEN_MAX} file descriptors currently open.
[ENFILE]: The system has too many files currently open.
[ENOMEM]: Not enough memory available.
[EINVAL]: The conversion from fromcode to tocode is not supported.

iconv_open( ) may use malloc(S) to allocate for its internal buffer areas and the routine iconv_open( ) may fail if there is not sufficient space for these buffers.

Warning

The use of the extended features provided for SCO OpenServer through flags _ICONV_DELETE and _ICONV_COMP without extra caution (e.g., conditional compiling) could make an application code non-XPG4 compliant. These features may not be supported in future release.

Standards conformance

iconv_open( ) and iconv_close( ) are conformant with:
X/Open CAE Specification, System Interfaces and Headers, Issue 4, 1992.

iconv( ) is conformant with:
X/Open CAE Specification, System Interfaces and Headers, Issue 4, 1992, with extensions that were developed by The Santa Cruz Operation and are maintained by The SCO Group.