### mbtowc -- Convert Multibyte Character to Wide Character

Format

>     #include <stdlib.h>
>     int mbtowc(wchar_t *pwc, const char *string, size_t n);

Language Level: ANSI, XPG4
mbtowc first determines the length of the multibyte character pointed to by string. It then converts the multibyte character to the corresponding wide character, and stores it in the location pointed to by pwc, if pwc is not a null pointer. mbtowc examines a maximum of n bytes from string.

If pwc is a null pointer, the multibyte character is not converted.

The LC_CTYPE category of the current locale affects the behavior of mbtowc.

Return Value
If string is NULL, mbtowc returns 0.

Note: On platforms that support shift states, mbtowc can also return a nonzero value to indicate that the multibyte encoding is state dependent. Because this product does not support state-dependent encoding, mbtowc always returns 0 when string is NULL.

If string is not NULL, mbtowc returns:

- The number of bytes comprising the converted multibyte character, if n or fewer bytes form a valid multibyte character.
- 0 if string points to the null character.
- -1 if string does not point to a valid multibyte character, and the next n bytes do not form a valid multibyte character.

Example
This example uses mbtowc to convert the second multibyte character in mbs to a wide character.

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

    #define LOCNAME "ja_jp.ibm-932"

    int main(void)
    {
       char     mb_string[] = "\x81\x41\x81\x42" "c" "\x00";
       int      length;
       wchar_t  widechar;

       if (NULL == setlocale(LC_ALL, LOCNAME)) {
          printf("Locale \"%s\" could not be loaded\n", LOCNAME);
          exit(1);
       }
       length = mblen(mb_string, MB_CUR_MAX);
       length = mbtowc(&widechar, mb_string + length, MB_CUR_MAX);
       printf("The wide character %lc has length of %d.\n", widechar, length);
       return 0;

       /***********************************************************************
          The output should be similar to:

          The second character  B has length 2 bytes.
       ***********************************************************************/
    }

mblen -- Determine Length of Multibyte Character
mbrtowc -- Convert Multibyte Character to Wide Character
mbsrtowcs -- Convert Multibyte String to Wide-Character String
setlocale -- Set Locale
wcrtomb -- Convert Wide Character to Multibyte Character
wcsrtombs -- Convert Wide-Character String to Multibyte String
<locale.h>
<wchar.h>