Parameters

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.

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.