mbtowc Function

Converts a multibyte character to a wide character.

Attention: This function is implemented only by MPLAB XC32 C compilers.




int mbtowc(wchar_t * restrict pwc, const char * restrict s, size_t n);


a pointer to where the converted multibyte character should be stored
the multibyte character to convert
The maximum number of bytes to consider for conversion

Return Value

If s is a null pointer, the function returns a nonzero or zero value, which indicates if multibyte character encodings, respectively, do or do not have state-dependent encodings.

If s is not a null pointer, the function returns 0 if s points to the null character, returns −1 if the processed bytes do not form a valid multibyte character, or returns the number of bytes of the converted multibyte character.

The returned value will never exceed n or the value of the MB_CUR_MAX macro.


If a valid multibyte character (including any shift sequences) can be formed from no more than the next n bytes of the sequence pointed to by s, that multibyte character is converted to a wide character that is then stored to the object pointed to by pwc, provided that pointer is not null. If the corresponding wide character is the null wide character, the function is left in the initial conversion state.


See the notes at the beginning of this chapter or section for information on using printf() or scanf() (and other functions reading and writing the stdin or stdout streams) in the example code.

#include <locale.h>
#include <wchar.h>
#include <stdlib.h>

void printWide(const char * mbstr)
  size_t len;
  wchar_t wstr;

  mbtowc(NULL, 0, 0); // reset the conversion state
  while(*mbstr) {
    len = mbtowc(&wstr, mbstr, 40);
    wprintf(L"%lc(%d)", wstr, len);
    mbstr += len;

int main(void)
    setlocale(LC_CTYPE, "");

Example Output