iconvstr

- string-based code conversion function

Synopsis

#include <iconv.h>

size_t iconvstr(const char *tocode, const char *fromcode,
    char *inarray, size_t *inlen, char *outarray, size_t *outlen,
    int flag);

Parameters

tocode

Pointer to a target codeset name string.

fromcode

Pointer to a source codeset name string.

inarray

Pointer to a byte array containing a sequence of character bytes in fromcode codeset to be converted.

inlen

As input argument, the number of bytes to be converted in inarray. As output argument, the number of bytes in inarray still not converted after the conversion.

outarray

Pointer to a byte array where converted character bytes in tocode codeset can be saved.

outlen

As input argument, the number of available bytes at outarray where converted character bytes can be saved. As output argument, after the conversion, the number of bytes still available at outarray.

flag

Indicates possible conversion options constructed by a bitwise-inclusive-OR of the following values:

ICONV_IGNORE_NULL

Normally iconvstr() stops the conversion if it encounters a string terminating null character of fromcode from inarray even if the value of inlen indicates there are more bytes in inarray.

With this option, the null character does not stop the conversion and the conversion continues until inlen pointed amount of inarray bytes are all consumed for conversion or an error occurred.

ICONV_REPLACE_INVALID

Normally iconvstr() stops the conversion if it encounters illegal or incomplete characters from inarray() with a corresponding errno value.

When this option is set, iconvstr() does not stop the conversion and instead treats such characters as non-identical conversion cases.

Description

The iconvstr() function converts the sequence of characters from one codeset, in the array specified by inarray, into a sequence of corresponding characters in another codeset, in the array specified by outarray. The codesets are those specified in fromcode and tocode arguments.

Unless ICONV_IGNORE_NULL is specified in flag, iconvstr() normally stops when it encounters a string terminating null character of fromcode from inarray regardless of the current inlen value; in that case, it does not copy over the null character to outarray.

If ICONV_REPLACE_INVALID is not specified in flag and if a sequence of input bytes does not form a valid character in the specified codeset, conversion stops after the previous successfully converted character.

If ICONV_REPLACE_INVALID is not specified in flag and if the input array ends with an incomplete character or shift sequence, conversion stops after the previous successfully converted bytes.

If the output array is not large enough to hold the entire converted input, conversion stops just prior to the input bytes that would cause the output array to overflow.

The value pointed to by inlen is decremented to reflect the number of bytes still not converted in the input array. The value pointed to by outlen is decremented to reflect the number of bytes still available in the output array.

If iconvstr() encounters a character in the input array that is legal, but for which an identical character does not exist in the target codeset, iconvstr() performs an implementation-defined conversion, i.e., non-identical conversion, on this character.

If ICONV_REPLACE_INVALID is specified in flag and if iconvstr() encounters illegal or incomplete characters in the input array, instead of stopping the conversion, iconvstr() treats such characters as if they are non-identical characters and does non-identical conversions on such character bytes.

Return Values

The iconvstr() function updates the values pointed to by inlen and outlen arguments to reflect the extent of the conversion and returns the number of non-identical conversions performed. If the entire string in the input array is converted, the value pointed to by inlen will be 0. If the input conversion is stopped due to any conditions mentioned above, the value pointed to by inlen will be non-zero and errno is set to indicate the condition. If an error occurs, iconvstr() returns (size_t) - 1 and sets errno to indicate the error.

Errors

The iconvstr() function will fail if:

E2BIG

Input conversion stopped due to lack of space in the output array.

EBADF

Requested conversion is not supported.

EILSEQ

Input conversion stopped due to an input byte that does not belong to the input codeset.

EINVAL

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

Examples

Example 1 Code conversion from ISO8859-2 to UTF-8

The following example converts null-terminated ISO8859-2 pathname string to UTF-8 string and, in doing so, treats illegal and incomplete characters as non-identical conversion cases. It also does not stop the conversion even if it encounters a null byte from the input array.

#include <stdio.h>
#include <string.h>
#include <errno.h>
#include <iconv.h>

        :

size_t ret;
char ib[MAXPATHLEN];
char ob[MAXPATHLEN];
size_t il, ol;

        :

/*
 * We got the pathname from somewhere.
 *
 * Calculate the length of input string including the terminating
 * NULL byte and prepare other arguments for the conversion.
 */
(void) strlcpy(ib, pathname, MAXPATHLEN);
il = strlen(ib) + 1;
ol = MAXPATHLEN;

/*
 * Do the conversion. If the ret > 0, that's the number of
 * non-identical character conversions happened during the conversion.
 * Regardless of whether we have conversion failure or not,
 * outarray could contain some converted characters.
 */
ret = iconvstr("UTF-8", "ISO-8859-2", ib, &il, ob, &ol,
        (ICONV_IGNORE_NULL|ICONV_REPLACE_INVALID));
if (ret == (size_t)-1) {
    /* Code conversion not supported? */
    if (errno == EBADF)
        return (-1);

    /* Output array too small? */
    if (errno == E2BIG)
        return (-2);

    /* Unknown error which isn't possible BTW. */
    return (-3);
}

        :

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

geniconvtbl(1), iconv(1), iconv(3C), iconv_close(3C), iconv_open(3C), iconvctl(C), iconv.h(3HEAD), geniconvtbl(4), attributes(5), iconv(5), iconv_unicode(5), iconv(5), standards(5)