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]
uconv_u16tou32, uconv_u16tou8, uconv_u32tou16, uconv_u32tou8, uconv_u8tou16, uconv_u8tou32 - Unicode encoding conversion functions

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/u8_textprep.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);

utf16str

utf16len

utf32str

utf32len

utf8str

utf8len

flag

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 ('\e0') 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 ('\e0') 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.

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

EILSEQ

E2BIG

EINVAL

EBADF

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/u8_textprep.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/u8_textprep.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/u8_textprep>
.
.
.
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);
}
.
.
.

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Committed
MT-Level	MT-Safe

attributes(5), uconv_u16tou32(9F)

The Unicode Standard (http://www.unicode.org)

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.