| MBRTOWC(3) | Library Functions Manual | MBRTOWC(3) | 
mbrtowc —
#include <wchar.h>
size_t
  
  mbrtowc(wchar_t
    * restrict pwc, const
    char * restrict s, size_t
    n, mbstate_t * restrict
    ps);
mbrtowc() usually converts the multibyte character
  pointed to by s to a wide character, and stores the wide
  character to the wchar_t object pointed to by pwc if
  pwc is non-NULL and
  s points to a valid character. The conversion happens in
  accordance with, and changes the conversion state described in the mbstate_t
  object pointed to by ps. This function may examine at
  most n bytes of the array beginning from
  s.
If s points to a valid character and the
    character corresponds to a nul wide character, then the
    mbrtowc() places the mbstate_t object pointed to by
    ps to an initial conversion state.
Unlike mbtowc(3),
    the mbrtowc() may accept the byte sequence pointed
    to by s not forming a complete multibyte character but
    which may be part of a valid character. In this case, this function will
    accept all such bytes and save them into the conversion state object pointed
    to by ps. They will be used at subsequent calls of
    this function to restart the conversion suspended.
The behaviour of mbrtowc() is affected by
    the LC_CTYPE category of the current locale.
These are the special cases:
mbrtowc() sets the conversion state object pointed
      to by ps to an initial state and always returns 0.
      Unlike mbtowc(3), the value
      returned does not indicate whether the current encoding of the locale is
      state-dependent.
    In this case, mbrtowc() ignores
        pwc and n, and is equivalent
        to the following call:
mbrtowc(NULL, "", 1, ps);
    
    mbrtowc() uses its own internal state object to
      keep the conversion state, instead of ps mentioned
      in this manual page.
    Calling any other functions in Standard
        C Library (libc, -lc) never changes the internal state of
        mbrtowc(), which is initialized at startup time
        of the program.
mbrtowc() returns:
mbrtowc() returns the number of bytes in the
      character.MB_CUR_MAX,
      this case can only occur if the array pointed to by
      s contains a redundant shift sequence.mbrtowc() sets errno to
      indicate the error.mbrtowc() may cause an error in the following case:
mbrtowc() function conforms to
  ISO/IEC 9899/AMD1:1995 (“ISO C90, Amendment
  1”). The restrict qualifier is added at ISO/IEC
  9899:1999 (“ISO C99”).
| February 4, 2002 | NetBSD 9.3 |