MBRTOWC(3)

💅 MBRTOWC(3) — Library Functions Manual 💅

okay bestie, gather round: this is the glow-up for mbrtowc(3), mbrtoc16(3), and mbrtoc32(3) — the restartable wide-character conversion trio. they’re iconic, they’re useful, and yes, they have lore. ✨

🌸 NAME 🌸

mbrtowc, mbrtoc16, mbrtoc32 — convert a character to a wide-character code (restartable)

🎀 LIBRARY 🎀

Standard C Library (libc, -lc)

✨ SYNOPSIS ✨

#include <wchar.h>

size_t
mbrtowc(wchar_t * restrict pc, const char * restrict s, size_t n,
    mbstate_t * restrict ps);

#include <uchar.h>

size_t
mbrtoc16(char16_t * restrict pc, const char * restrict s, size_t n,
    mbstate_t * restrict ps);

size_t
mbrtoc32(char32_t * restrict pc, const char * restrict s, size_t n,
    mbstate_t * restrict ps);

🦋 DESCRIPTION 🦋

okay so picture this: mbrtowc(), mbrtoc16(), and mbrtoc32() inspect at most n bytes pointed to by s to determine how many bytes are needed to complete the next multibyte character. 🔍

If a character can be completed, and pc is not NULL, the wide character represented by s gets stored in the wchar_t, char16_t, or char32_t that pc points to. slay. 💅

If s is NULL, these functions behave as if pc was NULL, s was an empty string (""), and n was 1. no cap.

The mbstate_t argument, ps, is used to keep track of the shift state. If it is NULL, these functions use an internal, static mbstate_t object, which is initialized to the initial conversion state at program startup. 🎀

And the way that a single char16_t is not large enough to represent certain multibyte characters means mbrtoc16() may need to be invoked multiple times to convert a single multibyte character sequence. it’s giving “one more time for the girlies in the back.” 😭

👑 RETURN VALUES 👑

The mbrtowc(), mbrtoc16(), and mbrtoc32() functions return:

• 0 — the next n or fewer bytes represent the null wide character (L'\0'). 💀
• >0 — the next n or fewer bytes represent a valid character, and these functions return the number of bytes used to complete the multibyte character. 🔥
• (size_t)-1 — an encoding error has occurred. The next n or fewer bytes do not contribute to a valid multibyte character. 🚨
• (size_t)-2 — the next n contribute to, but do not complete, a valid multibyte character sequence, and all n bytes have been processed. 😭

The mbrtoc16() function also returns:

• (size_t)-3 — the next character resulting from a previous call has been stored. No bytes from the input have been consumed. ✨

🙈 ERRORS 🙈

The mbrtowc(), mbrtoc16(), and mbrtoc32() functions will fail if:

• [EILSEQ] — an invalid multibyte sequence was detected.
• [EINVAL] — the conversion state is invalid.

🌈 SEE ALSO 🌈

mbtowc(3), multibyte(3), setlocale(3), wcrtomb(3)

⭐ STANDARDS ⭐

The mbrtowc(), mbrtoc16(), and mbrtoc32() functions conform to ISO/IEC 9899:2011 (“ISO C11”). 🫶

💖 xoxo, Debian — May 21, 2013 — MBRTOWC(3) 💖