mbtowc - convert a multibyte sequence to a wide character


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 multibyte character, con­
       verts  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 character, or if they contain an invalid  multi­
       byte  sequence, mbtowc returns -1. This can happen even if
       n >= MB_CUR_MAX, if the multibyte string  contains  redun­
       dant shift sequences.

       A different case is when s is not NULL but pwc is NULL. In
       this case the mbtowc function behaves  as  above,  excepts
       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 function, to  the  initial  state,  and
       returns  non-zero  if  the  encoding has non-trivial 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 failure.

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


CONFORMING TO

       ISO/ANSI C, UNIX98


SEE ALSO

       mbrtowc(3), mbstowcs(3), MB_CUR_MAX(3)


NOTES

       The behaviour of mbtowc depends on the  LC_CTYPE  category
       of the current locale.

       towc provides a better interface to the  same  functional­
       ity.


Man(1) output converted with man2html