Skip to content
Tutorials Center
My learning

Topics

C Reference Β· stdlib.h

C multibyte conversion functions

Reference for C multibyte text conversion: mblen(), mbtowc(), mbstowcs(), wcstombs() and the restartable mbrtowc(), with setlocale() and UTF-8 examples.

C strings are arrays of bytes, but human text is made of characters, and in UTF-8 one character can take one to four bytes. The multibyte functions in <stdlib.h> (and the restartable ones in <wchar.h>) translate between the multibyte form (char strings in the current locale's encoding) and the wide form (wchar_t, one value per character).

The main functions are mblen() (how many bytes does the next character use?), mbtowc() and wctomb() (one character), and mbstowcs() and wcstombs() (whole strings). Their behavior depends on the current locale, which a program selects with setlocale().

C
#include <stdlib.h>

int mblen(const char *s, size_t n);
size_t mbstowcs(wchar_t *restrict pwcs, const char *restrict s, size_t n);

Try it

C Counting characters in UTF-8 text

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

C Converting to wide characters and back

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Syntax

C
int    mblen   (const char *s, size_t n);
int    mbtowc  (wchar_t *restrict pwc, const char *restrict s, size_t n);
int    wctomb  (char *s, wchar_t wc);
size_t mbstowcs(wchar_t *restrict pwcs, const char *restrict s, size_t n);
size_t wcstombs(char *restrict s, const wchar_t *restrict pwcs, size_t n);
size_t mbrtowc (wchar_t *restrict pwc, const char *restrict s, size_t n, mbstate_t *restrict ps);
Name Description
s The multibyte string (or character). A null s in mblen, mbtowc and wctomb queries whether the encoding has shift states.
n Maximum number of bytes (mblen, mbtowc) or output elements (mbstowcs, wcstombs) to handle.
pwc, pwcs Where the wide character(s) are stored. mbstowcs(NULL, s, 0) only counts.
ps Conversion state for the restartable functions; start with a zeroed mbstate_t.

Returns: mblen and mbtowc return the number of bytes used, 0 for a null character, and -1 for an invalid sequence. mbstowcs and wcstombs return the number of elements written (not counting the terminator) or (size_t)-1 on an invalid sequence.

Errors / undefined behavior: if the output of mbstowcs or wcstombs does not fit in n, the result is not null-terminated. Passing an invalid pointer is undefined behavior.

Usage notes

  • Call setlocale(LC_ALL, "") or a named locale first. Programs start in the "C" locale, where only single-byte characters are guaranteed to work. Which locale names exist depends on the system; "C.UTF-8" worked on our runner, but check the return value.
  • strlen counts bytes, not characters. Use mbstowcs(NULL, s, 0) to count characters; this is the reason these functions matter for text in user interfaces.
  • wchar_t is 32 bits on Linux and 16 bits on Windows, where it holds UTF-16 code units. A single user-perceived "character" can also consist of several code points (combining marks), which these functions do not join.
  • mblen and mbtowc keep hidden state and are not thread-safe. Prefer the restartable mbrtowc, wcrtomb and mbsrtowcs from <wchar.h> in new code.
  • C11 <uchar.h> adds mbrtoc16, mbrtoc32 and the matching c16rtomb, c32rtomb for UTF-16 and UTF-32 conversion independent of the locale (see <uchar.h>).
  • Truncation: size the output buffer as strlen(s) + 1 wide characters at most, since one byte never produces more than one wide character.
  • Printing wide strings needs %ls in printf or wprintf, and a stream orientation; mixing narrow and wide output on one stream is an error.