MBRTOC8(3)

NAME
mbrtoc8 - Restartable multibyte to UTF-8 conversion

LIBRARY
libc

SYNOPSIS
#include <uchar.h>
size_t
mbrtoc8(char8_t * restrict pc8, const char * restrict s, size_t n, mbstate_t * restrict ps);

DESCRIPTION
The mbrtoc8 function decodes multibyte characters in the current locale and converts them to UTF-8, keeping state so it can restart after incremental progress.

Each call to mbrtoc8:
1.  examines up to n bytes starting at s,
2.  yields a UTF-8 code unit if available by storing it at *pc8,
3.  saves state at ps, and
4.  returns either the number of bytes consumed if any or a special return value.

Specifically:

•   If the multibyte sequence at s is invalid after any previous input saved at ps, or if an error occurs in decoding, mbrtoc8 returns (size_t)-1 and sets errno(2) to indicate the error.

•   If the multibyte sequence at s is still incomplete after n bytes, including any previous input saved in ps, mbrtoc8 saves its state in ps after all the input so far and returns (size_t)-2. All n bytes of input are consumed in this case.

•   If mbrtoc8 had previously decoded a multibyte character but has not yet yielded all the code units of its UTF-8 encoding, it stores the next UTF-8 code unit at *pc8 and returns (size_t)-3. input is consumed in this case.

•   If mbrtoc8 decodes the null multibyte character, then it stores zero at *pc8 and returns zero.

•   Otherwise, mbrtoc8 decodes a single multibyte character, stores the first (and possibly only) code unit in its UTF-8 encoding at *pc8, and returns the number of bytes consumed to decode the first multibyte character.

If pc8 is a null pointer, nothing is stored, but the effects on ps and the return value are unchanged.

If s is a null pointer, the mbrtoc8 call is equivalent to:

mbrtoc8( NULL,, 1,ps)

This always returns zero, and has the effect of resetting ps to the initial conversion state, without writing to pc8, even if it is nonnull.

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

IMPLEMENTATION NOTES
On well-formed input, the mbrtoc8 function yields either a Unicode scalar value in US-ASCII range, i.e., a 7-bit Unicode code point, or, over two to four successive calls, the leading and trailing code units in order of the UTF-8 encoding of a Unicode scalar value outside the US-ASCII range.

RETURN VALUES
The mbrtoc8 function returns:

0   [null] if mbrtoc8 decoded a null multibyte character.

i   [code unit] where 1 i n, if mbrtoc8 consumed i bytes of input to decode the next multibyte character, yielding a UTF-8 code unit.

(size_t)-3
    [continuation] if mbrtoc8 consumed no new bytes of input but yielded a UTF-8 code unit that was pending from previous input.

(size_t)-2
    [incomplete] if mbrtoc8 found only an incomplete multibyte sequence after all n bytes of input and any previous input, and saved its state to restart in the next call with ps.

(size_t)-1
    [error] if any encoding error was detected; errno(2) is set to reflect the error.

EXAMPLES
Print the UTF-8 code units of a multibyte string in hexadecimal text:

    char *s = ...;
    size_t n = ...;
    mbstate_t mbs = {0};    /* initial conversion state */
    while (n) {
            char8_t c8;
            size_t len;
            len = mbrtoc8(&c8, s, n, &mbs);
            switch (len) {
            case 0:         /* NUL terminator */
                    assert(c8 == 0);
                    goto out;
            default:        /* consumed input and yielded a byte c8 */
                    printf("0x%02hhx\n", c8);
                    break;
            case (size_t)-3: /* yielded a pending byte c8 */
                    printf("continue 0x%02hhx\n", c8);
                    break;
            case (size_t)-2: /* incomplete */
                    printf("incomplete\n");
                    goto readmore;
            case (size_t)-1: /* error */
                    printf("error: %d\n", errno);
                    goto out;
            }
            s += len;
            n -= len;
    }

ERRORS

[EILSEQ]
    The multibyte sequence cannot be decoded in the current locale as a Unicode scalar value.

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

SEE ALSO
c8rtomb(3), c16rtomb(3), c32rtomb(3), mbrtoc16(3), mbrtoc32(3), uchar(3) The Unicode Standard, Version 15.0 — Core Specification, The Unicode Consortium, September 2022, https://www.unicode.org/versions/Unicode15.0.0/UnicodeStandard-15.0.pdf. F. Yergeau, UTF-8, a transformation format of ISO 10646, RFC 3629, November 2003, Internet Engineering Task Force, https://datatracker.ietf.org/doc/html/rfc3629.

HISTORY
The mbrtoc8 function first appeared in NetBSD 11.0.