Tribblix: manual page: uconv

UCONV_U16TOU32(9F) Kernel Functions for Drivers UCONV_U16TOU32(9F)

NAME

uconv_u16tou32, uconv_u16tou8, uconv_u32tou16, uconv_u32tou8,
uconv_u8tou16, uconv_u8tou32 - Unicode encoding conversion functions

SYNOPSIS

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

int uconv_u16tou32(const uint16_t *utf16str, size_t *utf16len,
uint32_t *utf32str, size_t *utf32len, int flag);

int uconv_u16tou8(const uint16_t *utf16str, size_t *utf16len,
uchar_t *utf8str, size_t *utf8len, int flag);

int uconv_u32tou16(const uint32_t *utf32str, size_t *utf32len,
uint16_t *utf16str, size_t *utf16len, int flag);

int uconv_u32tou8(const uint32_t *utf32str, size_t *utf32len,
uchar_t *utf8str, size_t *utf8len, int flag);

int uconv_u8tou16(const uchar_t *utf8str, size_t *utf8len,
uint16_t *utf16str, size_t *utf16len, int flag);

int uconv_u8tou32(const uchar_t *utf8str, size_t *utf8len,
uint32_t *utf32str, size_t *utf32len, int flag);

INTERFACE LEVEL

illumos DDI specific (illumos DDI).

PARAMETERS

utf16str
A pointer to a UTF-16 character string.

utf16len
As an input parameter, the number of 16-bit unsigned
integers in utf16str as UTF-16 characters to be converted
or saved.

As an output parameter, the number of 16-bit unsigned
integers in utf16str consumed or saved during conversion.

utf32str
A pointer to a UTF-32 character string.

utf32len
As an input parameter, the number of 32-bit unsigned
integers in utf32str as UTF-32 characters to be converted
or saved.

As an output parameter, the number of 32-bit unsigned
integers in utf32str consumed or saved during conversion.

utf8str
A pointer to a UTF-8 character string.

utf8len
As an input parameter, the number of bytes in utf8str as
UTF-8 characters to be converted or saved.

As an output parameter, the number of bytes in utf8str
consumed or saved during conversion.

flag
The possible conversion options that are constructed by a
bitwise-inclusive-OR of the following values:

UCONV_IN_BIG_ENDIAN

The input parameter is in big endian byte ordering.

UCONV_OUT_BIG_ENDIAN

The output parameter should be in big endian byte
ordering.

UCONV_IN_SYSTEM_ENDIAN

The input parameter is in the default byte ordering
of the current system.

UCONV_OUT_SYSTEM_ENDIAN

The output parameter should be in the default byte
ordering of the current system.

UCONV_IN_LITTLE_ENDIAN

The input parameter is in little endian byte
ordering.

UCONV_OUT_LITTLE_ENDIAN

The output parameter should be in little endian byte
ordering.

UCONV_IGNORE_NULL

The null or U+0000 character should not stop the
conversion.

UCONV_IN_ACCEPT_BOM

If the Byte Order Mark (BOM, U+FEFF) character exists
as the first character of the input parameter,
interpret it as the BOM character.

UCONV_OUT_EMIT_BOM

Start the output parameter with Byte Order Mark (BOM,
U+FEFF) character to indicate the byte ordering if
the output parameter is in UTF-16 or UTF-32.

DESCRIPTION

The uconv_u16tou32() function reads the given utf16str in UTF-16
until U+0000 (zero) in utf16str is encountered as a character or
until the number of 16-bit unsigned integers specified in utf16len is
read. The UTF-16 characters that are read are converted into UTF-32
and the result is saved at utf32str. After the successful conversion,
utf32len contains the number of 32-bit unsigned integers saved at
utf32str as UTF-32 characters.

The uconv_u16tou8() function reads the given utf16str in UTF-16 until
U+0000 (zero) in utf16str is encountered as a character or until the
number of 16-bit unsigned integers specified in utf16len is read. The
UTF-16 characters that are read are converted into UTF-8 and the
result is saved at utf8str. After the successful conversion, utf8len
contains the number of bytes saved at utf8str as UTF-8 characters.

The uconv_u32tou16() function reads the given utf32str in UTF-32
until U+0000 (zero) in utf32str is encountered as a character or
until the number of 32-bit unsigned integers specified in utf32len is
read. The UTF-32 characters that are read are converted into UTF-16
and the result is saved at utf16str. After the successful conversion,
utf16len contains the number of 16-bit unsigned integers saved at
utf16str as UTF-16 characters.

The uconv_u32tou8() function reads the given utf32str in UTF-32 until
U+0000 (zero) in utf32str is encountered as a character or until the
number of 32-bit unsigned integers specified in utf32len is read. The
UTF-32 characters that are read are converted into UTF-8 and the
result is saved at utf8str. After the successful conversion, utf8len
contains the number of bytes saved at utf8str as UTF-8 characters.

The uconv_u8tou16() function reads the given utf8str in UTF-8 until
the null ('\0') byte in utf8str is encountered or until the number of
bytes specified in utf8len is read. The UTF-8 characters that are
read are converted into UTF-16 and the result is saved at utf16str.
After the successful conversion, utf16len contains the number of
16-bit unsigned integers saved at utf16str as UTF-16 characters.

The uconv_u8tou32() function reads the given utf8str in UTF-8 until
the null ('\0') byte in utf8str is encountered or until the number of
bytes specified in utf8len is read. The UTF-8 characters that are
read are converted into UTF-32 and the result is saved at utf32str.
After the successful conversion, utf32len contains the number of
32-bit unsigned integers saved at utf32str as UTF-32 characters.

During the conversion, the input and the output parameters are
treated with byte orderings specified in the flag parameter. When not
specified, the default byte ordering of the system is used. The byte
ordering flag value that is specified for UTF-8 is ignored.

When UCONV_IN_ACCEPT_BOM is specified as the flag and the first
character of the string pointed to by the input parameter is the BOM
character, the value of the BOM character dictates the byte ordering
of the subsequent characters in the string pointed to by the input
parameter, regardless of the supplied input parameter byte ordering
option flag values. If the UCONV_IN_ACCEPT_BOM is not specified, the
BOM as the first character is treated as a regular Unicode character:
Zero Width No Break Space (ZWNBSP) character.

When UCONV_IGNORE_NULL is specified, regardless of whether the input
parameter contains U+0000 or null byte, the conversion continues
until the specified number of input parameter elements at utf16len,
utf32len, or utf8len are entirely consumed during the conversion.

As output parameters, utf16len, utf32len, and utf8len are not changed
if conversion fails for any reason.

CONTEXT

The uconv_u16tou32(), uconv_u16tou8(), uconv_u32tou16(),
uconv_u32tou8(), uconv_u8tou16(), and uconv_u8tou32() functions can
be called from user or interrupt context.

RETURN VALUES

Upon successful conversion, the functions return 0. Upon failure, the
functions return one of the following errno values:

EILSEQ
The conversion detected an illegal or out of bound
character value in the input parameter.

E2BIG
The conversion cannot finish because the size specified in
the output parameter is too small.

EINVAL
The conversion stops due to an incomplete character at the
end of the input string.

EBADF
Conflicting byte-ordering option flag values are detected.

EXAMPLES

Example 1: Convert a UTF-16 string in little-endian byte ordering into

UTF-8 string.

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/sunddi.h>
.
.
.
uint16_t u16s[MAXNAMELEN + 1];
uchar_t u8s[MAXNAMELEN + 1];
size_t u16len, u8len;
int ret;
.
.
.
u16len = u8len = MAXNAMELEN;
ret = uconv_u16tou8(u16s, &u16len, u8s, &u8len,
UCONV_IN_LITTLE_ENDIAN);
if (ret != 0) {
/* Conversion error occurred. */
return (ret);
}
.
.
.

Example 2: Convert a UTF-32 string in big endian byte ordering into

little endian UTF-16.

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/sunddi.h>
.
.
.
/*
* An UTF-32 character can be mapped to an UTF-16 character with
* two 16-bit integer entities as a "surrogate pair."
*/
uint32_t u32s[101];
uint16_t u16s[101];
int ret;
size_t u32len, u16len;
.
.
.
u32len = u16len = 100;
ret = uconv_u32tou16(u32s, &u32len, u16s, &u16len,
UCONV_IN_BIG_ENDIAN | UCONV_OUT_LITTLE_ENDIAN);
if (ret == 0) {
return (0);
} else if (ret == E2BIG) {
/* Use bigger output parameter and try just one more time. */
uint16_t u16s2[201];

u16len = 200;
ret = uconv_u32tou16(u32s, &u32len, u16s2, &u16len,
UCONV_IN_BIG_ENDIAN | UCONV_OUT_LITTLE_ENDIAN);
if (ret == 0)
return (0);
}

/* Otherwise, return -1 to indicate an error condition. */
return (-1);

Example 3: Convert a UTF-8 string into UTF-16 in little-endian byte

ordering.

Convert a UTF-8 string into UTF-16 in little-endian byte ordering
with a Byte Order Mark (BOM) character at the beginning of the output
parameter.

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/sunddi.h>
.
.
.
uchar_t u8s[MAXNAMELEN + 1];
uint16_t u16s[MAXNAMELEN + 1];
size_t u8len, u16len;
int ret;
.
.
.
u8len = u16len = MAXNAMELEN;
ret = uconv_u8tou16(u8s, &u8len, u16s, &u16len,
UCONV_IN_LITTLE_ENDIAN | UCONV_EMIT_BOM);
if (ret != 0) {
/* Conversion error occurred. */
return (ret);
}
.
.
.

ATTRIBUTES

NOTES

Each UTF-16 or UTF-32 character maps to an UTF-8 character that might
need one to maximum of four bytes.

One UTF-32 or UTF-8 character can yield two 16-bit unsigned integers
as a UTF-16 character, which is a surrogate pair if the Unicode
scalar value is bigger than U+FFFF.

Ill-formed UTF-16 surrogate pairs are seen as illegal characters
during the conversion.

September 18, 2007 UCONV_U16TOU32(9F)