C32RTOMB(3) Library Functions Manual C32RTOMB(3)

c32rtomb — Restartable UTF-32 to multibyte conversion

Standard C Library (libc, -lc)

#include <uchar.h>

size_t
c32rtomb(char * restrict s, char32_t c32, mbstate_t * restrict ps);

The c32rtomb function converts Unicode scalar values to multibyte characters in the current locale, keeping state to remember incremental progress if restarted.

Each call to c32rtomb updates the conversion state ps with a UTF-32 code unit c32, writes up to MB_CUR_MAX bytes to s, and returns either the number of bytes written to s or (size_t)-1 to denote error.

The input c32 is a UTF-32 code unit, representing a Unicode scalar value, i.e., a Unicode code point that is not a surrogate code point — in other words, c32 is an integer either in [0,0xd7ff] or in [0xe000,0x10ffff].

If s is a null pointer, no output is produced and ps is reset to the initial conversion state, as if the call had been (buf, 0, ps); for some internal buffer buf.

If c32 is zero, c32rtomb outputs a (possibly empty) shift sequence to restore the initial state followed by a NUL byte and resets ps to the initial conversion state.

If ps is a null pointer, c32rtomb uses an internal mbstate_t object with static storage duration, distinct from all other mbstate_t objects (including those used by other functions such as mbrtoc32(3)), which is initialized at program startup to the initial conversion state.

The c32rtomb function returns the number of bytes written to s on success, or sets errno(2) and returns (size_t)-1 on failure.

Convert a sequence of Unicode scalar values to a multibyte sequence, NUL-terminate it (with any shift sequence needed to restore the initial state), and print it:

char32_t c32[] = { 0x1f4a9, 0x20ac, 0x21 };
char buf[(__arraycount(c32) + 1)*MB_LEN_MAX], *s = buf;
size_t i;
mbstate_t mbs = {0};    /* initial conversion state */

for (i = 0; i < __arraycount(c32); i++) {
        size_t len;

        len = c32rtomb(s, c32[i], &mbs);
        if (len == (size_t)-1)
                err(1, "c32rtomb");
        assert(len < sizeof(buf) - (s - buf));
        s += len;
}
len = c32rtomb(s, 0, &mbs);             /* NUL-terminate */
if (len == (size_t)-1)
        err(1, "c32rtomb");
assert(len <= sizeof(buf) - (s - buf));
printf("%s\n", buf);

To avoid a variable-length array, this code uses MB_LEN_MAX, which is a constant upper bound on the locale-dependent MB_CUR_MAX.

[]
c32 is not a Unicode scalar value, i.e., it is a surrogate code point in the interval [0xd800,0xdfff] or it lies outside the Unicode codespace [0,0x10ffff] altogether.
[]
The input cannot be encoded as a multibyte sequence in the current locale.
[]
An error occurred in loading the locale's character conversions.

c16rtomb(3), c8rtomb(3), mbrtoc16(3), mbrtoc32(3), mbrtoc8(3), uchar(3)

The Unicode Standard, https://www.unicode.org/versions/Unicode15.0.0/UnicodeStandard-15.0.pdf, The Unicode Consortium, September 2022, Version 15.0 — Core Specification.

The c32rtomb function conforms to ISO/IEC 9899:2011 (“ISO C11”).

The c32rtomb function first appeared in NetBSD 11.0.

August 14, 2024 NetBSD 11.0