SYNOPSIS
       #include <stdlib.h>

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

DESCRIPTION
       The  main  case  for this function is when s is not NULL and pwc is not
       NULL.  In this case, the mbtowc() function inspects at most n bytes  of
       the  multibyte  string starting at s, extracts the next complete multi-
       byte character, converts it to a wide character and stores it at  *pwc.
       It  updates  an internal shift state only known to the mbtowc function.
       If s does not point to a '\0' byte, it returns the number of bytes that
       were consumed from s, otherwise it returns 0.

       If  the n bytes starting at s do not contain a complete multibyte char-
       acter, or if they  contain  an  invalid  multibyte  sequence,  mbtowc()
       returns  -1.  This can happen even if n >= MB_CUR_MAX, if the multibyte
       string contains redundant shift sequences.

       A different case is when s is not NULL but pwc is NULL.  In  this  case
       the  mbtowc()  function behaves as above, except that it does not store
       the converted wide character in memory.

       A third case is when s is NULL.  In this case, pwc and n  are  ignored.
       The  mbtowc() function resets the shift state, only known to this func-
       tion, to the initial state, and returns non-zero if  the  encoding  has
       nontrivial shift state, or zero if the encoding is stateless.

RETURN VALUE
       If  s is not NULL, the mbtowc() function returns the number of consumed
       bytes starting at s, or 0 if s points to a null byte, or -1 upon  fail-
       ure.

       If  s  is  NULL, the mbtowc() function returns non-zero if the encoding
       has nontrivial shift state, or zero if the encoding is stateless.

CONFORMING TO
       C99.

NOTES
       The behavior of mbtowc() depends on the LC_CTYPE category of  the  cur-
       rent locale.

       this  function  is  not multithread safe.  the function mbrtowc(3) pro-
       vides a better interface to the same functionality.

SEE ALSO
       mb_cur_max(3), mbrtowc(3), mbstowcs(3)

COLOPHON
       This page is part of release 3.23 of the Linux  man-pages  project.   A
       description  of  the project, and information about reporting bugs, can