MBTOWC(3)		   Linux Programmers Manual		    MBTOWC(3)



NAME
       mbtowc - convert a multibyte sequence to a wide character

SYNOPSIS
       #include 

       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 multi-thread 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.05 of the Linux  man-pages  project.   A
       description  of	the project, and information about reporting bugs, can
       be found at http://www.kernel.org/doc/man-pages/.



GNU				  2001-07-04			     MBTOWC(3)