Updated: 2025/Nov/16

Please read Privacy Policy. It's for your privacy.

C32RTOMB(3)                Library Functions Manual                C32RTOMB(3)

NAME
     c32rtomb - Restartable UTF-32 to multibyte conversion

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <uchar.h>

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

DESCRIPTION
     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 c8rtomb(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.

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

EXAMPLES
     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.

ERRORS
     [EILSEQ]      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.

     [EILSEQ]      The input cannot be encoded as a multibyte sequence in the
                   current locale.

     [EIO]         An error occurred in loading the locale's character
                   conversions.

SEE ALSO
     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.

STANDARDS
     The c32rtomb function conforms to ISO/IEC 9899:2011 ("ISO C11").

HISTORY
     The c32rtomb function first appeared in NetBSD 11.0.

NetBSD 11.99                    August 14, 2024                   NetBSD 11.99