NAME

       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, converts it to a wide character and stores it at *pwc. It updates an internal shift
       state only known to the mbtowc function. It 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
       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, 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.

       This function is not multi-thread safe. The function mbrtowc provides a  better  interface  to  the  same
       functionality.

GNU                                               July 25, 1999                                        MBTOWC(3)