Standard C Library Functions uconv_u16tou32(3C)
NAME
uconv_u16tou32, uconv_u16tou8, uconv_u32tou16,
uconv_u32tou8, uconv_u8tou16, uconv_u8tou32 - Unicode encod-
ing conversion functionsSYNOPSIS
#include
#include
#include
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);
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 charac-
ters 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
SunOS 5.11 Last change: 18 Sep 2007 1
Standard C Library Functions uconv_u16tou32(3C)
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 inutf8str 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 con-
structed by a bitwise-inclusive-OR of the fol-
lowing 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.SunOS 5.11 Last change: 18 Sep 2007 2
Standard C Library Functions uconv_u16tou32(3C)
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) charac-
ter 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 inUTF-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 con-
tains 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 containsthe 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
SunOS 5.11 Last change: 18 Sep 2007 3
Standard C Library Functions uconv_u16tou32(3C)
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 con-
tains 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 containsthe 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 successfulconversion, 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 successfulconversion, utf32len contains the number of 32-bit unsigned
integers saved at utf32str as UTF-32 characters.
During the conversion, the input and the output parametersare treated with byte orderings specified in the flag param-
eter. When not specified, the default byte ordering of thesystem is used. The byte ordering flag value that is speci-
fied 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 param-
eter 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 flagvalues. If the UCONV_IN_ACCEPT_BOM is not specified, the BOM
as the first character is treated as a regular Unicode char-
acter: Zero Width No Break Space (ZWNBSP) character.SunOS 5.11 Last change: 18 Sep 2007 4
Standard C Library Functions uconv_u16tou32(3C)
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.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 charac-
ter 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 ord-
ering into UTF-8 string.
#include
#include
#include
. . .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) {SunOS 5.11 Last change: 18 Sep 2007 5
Standard C Library Functions uconv_u16tou32(3C)
/* Conversion error occurred. */ return (ret); } . . .Example 2 Convert a UTF-32 string in big endian byte order-
ing into little endian UTF-16.
#include
#include
#include
. . . /** 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.SunOS 5.11 Last change: 18 Sep 2007 6
Standard C Library Functions uconv_u16tou32(3C)
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
#include
#include
. . .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
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
attributes(5), uconv_u16tou32(9F)
The Unicode Standard (http://www.unicode.org)SunOS 5.11 Last change: 18 Sep 2007 7
Standard C Library Functions uconv_u16tou32(3C)
NOTESEach 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 char-
acters during the conversion.SunOS 5.11 Last change: 18 Sep 2007 8