c16rtomb(), c32rtomb()

Updated: April 19, 2023

Convert a wide character (UTF-16 or UTF-32) into a multibyte character (UTF-8)

Synopsis:

#include <uchar.h>

size_t c16rtomb( char *s,
                 char16_t wc,
  	         mbstate_t *pst );

size_t c32rtomb( char *s,
                 char32_t wc,
  	         mbstate_t *pst );

Arguments:

s
NULL, or an array of characters where the function can store the multibyte character.
wc
The wide character that you want to convert.
pst
A pointer to a conversion object that's used to store state information so that the function can be restarted. You can call mbsinit() to determine the status of this variable.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

If s isn't NULL, the c16rtomb() and c32rtomb() functions convert the wide character wc (UTF-16 for type char16_t or UTF-32 for type char32_t) into a multibyte character (UTF-8). The multibyte character is stored in the location referenced by s, to a maximum of MB_CUR_MAX bytes.

If s is NULL, the function call is equivalent to
c16rtomb(buf, L'\0', pst)
or
c32rtomb(buf, L'\0', pst)
where buf is an internal buffer. The mbstate_t object referenced by pst is then reset to its initial conversion state.

Returns:

The number of bytes needed to convert the wide character, or -1 if wc isn't a valid wide character.

Classification:

C11

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes