KICONVSTR(9F)KICONVSTR(9F)NAMEkiconvstr - string-based code conversion function
SYNOPSIS
#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);
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. Supported names are
specified at kiconv_open().
fromcode
Points to a source codeset name string. Supported names are
specified at kiconv_open().
inarray
Points to a byte array containing a sequence of character
bytes in fromcode codeset to be converted.
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 converted 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 constructed by a bit‐
wise-inclusive-OR of the 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 not stop the
conversion and the conversion continues until the num‐
ber 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 characters with corre‐
sponding errno values.
If this option is set, kiconvstr() does not stop the
conversion and instead treats such characters as non-
identical conversion cases.
errno
Indicates the error when conversion is not completed 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.
DESCRIPTION
The kiconvstr() function converts the sequence of characters from one
codeset, in the array specified by inarray, into a sequence of corre‐
sponding characters in another codeset, in the array specified by out‐
array. The codesets are those specified in fromcode and tocode parame‐
ters. 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, conver‐
sion 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 code‐
set, 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 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.
CONTEXTkiconvstr() can be called from user or interrupt context.
EXAMPLES
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);
}
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌────────────────────┬─────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├────────────────────┼─────────────────┤
│Interface Stability │ Committed │
└────────────────────┴─────────────────┘
SEE ALSOiconv(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.html
Oct 16, 2007 KICONVSTR(9F)
