te
Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
kiconvstr - string-based code conversion function

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/sunddi.h>



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

illumos DDI specific (illumos DDI). The parameters for the kiconvstr function are as follows: tocode fromcode inarray inlen outarray outlen flag errno The kiconvstr() 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 parameters. The inarray parameter points to a character byte array to the first character in the input array and inlen indicates the number of bytes to the end of the array to be converted. The outarray parameter points to a character byte array to the first available byte in the output array and outlen indicates the number of the available bytes to the end of the array. Unless KICONV_IGNORE_NULL is specified at flag, kiconvstr() function normally stops when it encounters NULL byte from the input array regardless of the current inlen value.

If KICONV_REPLACE_INVALID is not specified at 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 KICONV_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 kiconvstr() encounters a character in the input array that is legal, but for which an identical character does not exist in the target codeset, kiconvstr() performs an implementation-defined conversion (that is, a non-identical conversion) on this character.

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

The kiconvstr() function updates the values pointed to by the inlen and outlen parameters 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 is 0. If the input conversion is stopped due to any conditions mentioned above, the value pointed to by inlen is non-zero and errno is set to indicate the condition. If an error occurs, kiconvstr() returns (size_t)-1 and sets errno to indicate the error. kiconvstr() can be called from user or interrupt context. Example 1 Performing a Code Conversion

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

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/sunddi.h>

 :

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

 :

/*
 * We got the pathname from somewhere.
 *
 * Calculate the length of input string including the terminating
 * NULL byte and prepare other parameters 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 = kiconvstr("UTF-8", "ISO-8859-2", ib, &il, ob, &ol,
 (KICONV_IGNORE_NULL|KICONV_REPLACE_INVALID), &err);
if (ret == (size_t)-1) {
 /* Code conversion not supported? */
 if (err == EBADF)
 return (-1);

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

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

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

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability Committed

iconv (3C), iconv_close (3C), iconv_open (3C), u8_strcmp (3C), u8_textprep_str (3C), u8_validate (3C), uconv_u16tou32 (3C), uconv_u16tou8 (3C), uconv_u32tou16 (3C), uconv_u32tou8 (3C), uconv_u8tou16 (3C), uconv_u8tou32 (3C), attributes (7), kiconv (9F), kiconv_close (9F), kiconv_open (9F), u8_strcmp (9F), u8_textprep_str (9F), u8_validate (9F), uconv_u16tou32 (9F), uconv_u16tou8 (9F), uconv_u32tou16 (9F), uconv_u32tou8 (9F), uconv_u8tou16 (9F), uconv_u8tou32 (9F)

The Unicode Standard:

http://www.unicode.org/standard/standard.html