Kernel Functions for Drivers kiconvstr(9F)
NAME
kiconvstr - string-based code conversion function
SYNOPSIS
#include
#include
#include
size_t kiconvstr(const char *tocode, const char *fromcode, char *inarray,
size_t *inlen, char *outarray, size_t *outlen, int flag, int *errno);
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI).PARAMETERS
The parameters for the kiconvstr function are as follows:
tocode Points to a target codeset name string. Sup-
ported names are specified at kiconv_open().
fromcode Points to a source codeset name string. Sup-
ported names are specified at kiconv_open().
inarray Points to a byte array containing a sequence ofcharacter bytes in fromcode codeset to be con-
verted. inlen As an input parameter, the number of bytes to be converted in inarray. As an output parameter,the number of bytes in inarray still not con-
verted after the conversion. outarray Points to a byte array where converted character bytes in tocode codeset can be saved. outlen As an input parameter, the number of available bytes at outarray where converted character bytes can be saved. As an output parameter, the number of bytes still available at outarray after the conversion.flag Indicates possible conversion options con-
structed by a bitwise-inclusive-OR of the
SunOS 5.11 Last change: 16 Oct 2007 1
Kernel Functions for Drivers kiconvstr(9F)
following values:KICONV_IGNORE_NULL
Normally, kiconvstr() stops the conversion
if it encounters NULL byte even if the current inlen is pointing to a value larger than zero. If this option is set, a NULL byte does notstop the conversion and the conversion con-
tinues until the number of inarray bytes pointed by inlen are all consumed for conversion or an error happened.KICONV_REPLACE_INVALID
Normally, kiconvstr() stops the conversion
if it encounters illegal or incomplete char-
acters with corresponding errno values.If this option is set, kiconvstr() does not
stop the conversion and instead treats suchcharacters as non-identical conversion
cases.errno Indicates the error when conversion is not com-
pleted or failed. The following are possible values: EILSEQ The input conversion was stopped due to an input byte that does not belong to the input codeset. E2BIG The input conversion was stopped due to lack of space in the output array. EINVAL The input conversion was stopped due to an incomplete character or shift sequence at the end of the input array. EBADF The requested conversion is not supported.SunOS 5.11 Last change: 16 Oct 2007 2
Kernel Functions for Drivers kiconvstr(9F)
DESCRIPTION
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 numberof bytes to the end of the array to be converted. The outar-
ray 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 previoussuccessfully 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 stopsafter the previous successfully converted bytes. If the out-
put 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 notexist 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.RETURN VALUES
The kiconvstr() function updates the values pointed to by
the inlen and outlen parameters to reflect the extent of theconversion and returns the number of non-identical conver-
sions performed. If the entire string in the input array isSunOS 5.11 Last change: 16 Oct 2007 3
Kernel Functions for Drivers kiconvstr(9F)
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.
CONTEXT
kiconvstr() can be called from user or interrupt context.
EXAMPLES
Example 1 Performing a Code ConversionThe 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
#include
#include
: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);
SunOS 5.11 Last change: 16 Oct 2007 4
Kernel Functions for Drivers kiconvstr(9F)
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);
}ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
SEE ALSO
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(5),
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.htmlSunOS 5.11 Last change: 16 Oct 2007 5