MBTOWC(C)           Linux Programmer's Manual           MBTOWC(C)



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, 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(c), mbstowcs(s), MB_CUR_MAX(X)

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

       This  function is not multi-thread safe. The function mbr-
       towc provides a better interface to the  same  functional-
       ity.



GNU                         2001-07-04                  MBTOWC(C)