c32rtomb(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
C32RTOMB(3)             NetBSD 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 charac-
     ters 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 num-
     ber 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 ini-
     tial 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 suc-
     cess, 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 out-
                   side 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 conver-
                   sions.


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 10.99                    August 14, 2024                   NetBSD 10.99