Kernel Functions for Drivers kiconvstr(9F)
NAME
kiconvstr - string-based code conversion function
SYNOPSIS
#include
#include
#include
sizet kiconvstr(const char *tocode, const char *fromcode, char *inarray,
sizet *inlen, char *outarray, sizet *outlen, int flag, int *errno);
INTERFACE LEVEL
Solaris DI specific (Solaris DI).
PARAMETERS
The parameters for the kiconvstr function are as follows:
tocode Points to a target codeset name string. Sup-
ported names are specified at kiconvopen().
fromcode Points to a source codeset name string. Sup-
ported names are specified at kiconvopen().
inarray Points to a byte array containing a sequence of
character 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:
KICONVIGNORENUL
Normally, kiconvstr() stops the conversion
if it encounters NUL byte even if the
current inlen is pointing to a value larger
than zero.
If this option is set, a NUL byte does not
stop 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.
KICONVREPLACEINVALID
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 such
characters 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 number
of 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 KICONVIGNORENUL is specified at flag, kiconvstr()
function normally stops when it encounters NUL byte from
the input array regardless of the current inlen value.
If KICONVREPLACEINVALID 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 KICONVREPLACEINVALID
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 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 not
exist in the target codeset, kiconvstr() performs an
implementation-defined conversion (that is, a non-identical
conversion) on this character.
If KICONVREPLACEINVALID 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 conver-
sions performed. If the entire string in the input array is
SunOS 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 (sizet)-1 and sets errno to indicate the error.
CONTEXT
kiconvstr() can be called from user or interrupt context.
EXAMPLES
Example 1 Performing a Code Conversion
The following example converts a NUL-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 NUL byte
from the input array.
#include
#include
#include
:
sizet ret;
char ib[MAXPATHLEN];
char ob[MAXPATHLEN];
sizet il, ol;
int err;
:
/*
* We got the pathname from somewhere.
*
* Calculate the length of input string including the terminating
* NUL 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,
(KICONVIGNORENULKICONVREPLACEINVALID), &err);
SunOS 5.11 Last change: 16 Oct 2007 4
Kernel Functions for Drivers kiconvstr(9F)
if (ret == (sizet)-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);
}
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
SEE ALSO
iconv(3C), iconvclose(3C), iconvopen(3C), u8strcmp(3C),
u8textprepstr(3C), u8validate(3C), uconvu16tou32(3C),
uconvu16tou8(3C), uconvu32tou16(3C), uconvu32tou8(3C),
uconvu8tou16(3C), uconvu8tou32(3C), attributes(5),
kiconv(9F), kiconvclose(9F), kiconvopen(9F),
u8strcmp(9F), u8textprepstr(9F), u8validate(9F),
uconvu16tou32(9F), uconvu16tou8(9F), uconvu32tou16(9F),
uconvu32tou8(9F), uconvu8tou16(9F), uconvu8tou32(9F)
The Unicode Standard:
http:/www.unicode.org/standard/standard.html
SunOS 5.11 Last change: 16 Oct 2007 5
|
