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);
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
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;
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:
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
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.
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.
iconv( ) and iconv_close( ) may fail if the following is true:
iconv_open( ) may fail if any one of the following is true:
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.
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.