Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / C

mbrtoc32 — C23 Unicode-conversion function

`mbrtoc32(pc32, s, n, ps)` from `<uchar.h>` converts at most `n` bytes of the next execution multibyte character to a UTF-32 `char32_t` unit. Its `mbstate_t` state lets a character continue across buffer boundaries; a null `pc32` still performs conversion but suppresses the store.

Version: C23

Syntax

size_t mbrtoc32(char32_t * restrict pc32, const char * restrict s, size_t n, mbstate_t * restrict ps);

mbrtoc32(pc32, s, n, ps) from <uchar.h> converts at most n bytes of the next execution multibyte character to a UTF-32 char32_t unit. Its mbstate_t state lets a character continue across buffer boundaries; a null pc32 still performs conversion but suppresses the store.

The example passes a zero-initialized state and the single-byte string "Z". mbrtoc32 returns the consumed-byte count 1, stores U+0000005A, and the complete program output is 1 U+0000005A.

A return of 0 denotes the null character and restoration of initial state; -2 requests more bytes, -1 means EILSEQ and leaves state unspecified, while -3 can deliver a further result from the previous character without consuming input. After -2, continue with remaining bytes and the same ps; after -3, do not advance input. When s == NULL, the call is exactly equivalent to mbrtoc32(NULL, "", 1, ps); pc32 and n are ignored. This is the specified empty-string call in the current conversion state, not a promise of an unconditional reset. With non-null s, pc32 == NULL suppresses only the store; explicit ps avoids internal state that is not required to be race-free.

Examples

#include <stdio.h>
#include <uchar.h>
int main(void){mbstate_t state={0};char32_t unit=0;size_t count=mbrtoc32(&unit,"Z",1,&state);printf("%zu U+%08X\n",count,(unsigned)unit);return 0;}

Result

1 U+0000005A

The example passes a zero-initialized state and the single-byte string `"Z"`. `mbrtoc32` returns the consumed-byte count `1`, stores `U+0000005A`, and the complete program output is `1 U+0000005A`.

Sources