Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Friday, August 13, 2021
 
 

mbrtoc16 (3C)

Name

mbrtoc16 - restartable multibyte/wide character conversion function

Synopsis

#include <uchar.h>
size_t mbrtoc16(char16_t * restrict pc16, const char * restrict s, size_t n, mbstate_t *restrict ps);

Description

If s is a null pointer, the mbrtoc16() function is equivalent to the call:

mbrtoc16(NULL, "", 1, ps)

In this case, the values of the parameters pc16 and n are ignored.

If s is not a null pointer, the mbrtoc16() function inspects at most n bytes beginning with the byte pointed to by s to determine the number of bytes needed to complete the next multibyte character (including any shift sequences). If the function determines that the next multibyte character is complete and valid, it determines the values of the corresponding wide characters and then, if pc16 is not a null pointer, stores the value of the first (or only) such character in the object pointed to by pc16. Subsequent calls will store successive wide characters without consuming any additional input until all the characters have been stored. If the corresponding wide character is the null wide character, the resulting state described is the initial conversion state.

Return Values

The mbrtoc16() function returns the first of the following that applies (given the current conversion state):

0

if the next n or fewer bytes complete the multibyte character that corresponds to the null wide character (which is the value stored).

between 1 and n inclusive

if the next n or fewer bytes complete a valid multibyte character (which is the value stored); the value returned is the number of bytes that complete the multibyte character.

(size_t)(-3)

if the next character resulting from a previous call has been stored (no bytes from the input have been consumed by this call).

(size_t)(-2)

if the next n bytes contribute to an incomplete (but potentially valid) multibyte character, and all n bytes have been processed (no value is stored).

(size_t)(-1)

if an encoding error occurs, in which case the next n or fewer bytes do not contribute to a complete and valid multibyte character (no value is stored); the value of the macro EILSEQ is stored in errno, and the conversion state is unspecified.

Errors

The mbrtoc16() function will fail if:

EINVAL

The ps argument points to an object that contains an invalid conversion state.

EILSEQ

Invalid character sequence is detected.

The mbrtoc16() function may fail if:

ENOMEM

Insufficient storage space is available.

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
See NOTES below
Standard

See Also

mbsinit(3C), setlocale(3C), attributes(7), standards(7)

Notes

If ps is not a null pointer, the function uses the mbstate_t object pointed to by ps and the function can be used safely in multithreaded applications. If ps is a null pointer, the function uses its internal mbstate_t object and the function is Unsafe in multithreaded applications.