Updated: 2025/Nov/16

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

C16RTOMB(3)                Library Functions Manual                C16RTOMB(3)

NAME
     c16rtomb - Restartable UTF-16 to multibyte conversion

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <uchar.h>

     size_t
     c16rtomb(char * restrict s, char16_t c16, mbstate_t * restrict ps);

DESCRIPTION
     The c16rtomb function decodes UTF-16 and converts it to multibyte
     characters in the current locale, keeping state to remember incremental
     progress if restarted.

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

     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 c16 is zero, c16rtomb discards any pending incomplete UTF-16 code unit
     sequence in ps, 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, c16rtomb 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 mbrtoc16(3)), which is
     initialized at program startup to the initial conversion state.

RETURN VALUES
     The c16rtomb 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 UTF-16 code unit sequence to a multibyte string, NUL-terminate
     it (with any shift sequence needed to restore the initial state), and
     print it:

           char16_t c16[] = { 0xd83d, 0xdca9 };
           char buf[(__arraycount(c16) + 1)*MB_LEN_MAX], *s = buf;
           size_t i;
           mbstate_t mbs = {0};    /* initial conversion state */

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

                   len = c16rtomb(s, c16[i], &mbs);
                   if (len == (size_t)-1)
                           err(1, "c16rtomb");
                   assert(len < sizeof(buf) - (s - buf));
                   s += len;
           }
           len = c16rtomb(s, 0, &mbs);             /* NUL-terminate */
           if (len == (size_t)-1)
                   err(1, "c16rtomb");
           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]      c16 is invalid as the next code unit in the conversion
                   state ps.

     [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
     c32rtomb(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.

     P. Hoffman and F. Yergeau, UTF-16, an encoding of ISO 10646, Internet
     Engineering Task Force, RFC 2781,
     https://datatracker.ietf.org/doc/html/rfc2781, February 2000.

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

HISTORY
     The c16rtomb function first appeared in NetBSD 11.0.

BUGS
     The standard requires that passing zero as c16 unconditionally reset the
     conversion state and output a NUL byte:

           If c16 is a null wide character, a null byte is stored, preceded by
           any shift sequence needed to restore the initial shift state; the
           resulting state described is the initial conversion state.

     However, some implementations such as FreeBSD 14.0, OpenBSD 7.4, and
     glibc 2.36 ignore this clause and, if the zero was preceded by an
     incomplete UTF-16 code unit sequence, fail with EILSEQ instead.

NetBSD 11.99                    August 14, 2024                   NetBSD 11.99