NAME    [Toc]    [Back]

     mbtowc - converts a multibyte character to a wide character

LIBRARY    [Toc]    [Back]

     Standard C Library (libc, -lc)

SYNOPSIS    [Toc]    [Back]

     #include <stdlib.h>

     int
     mbtowc(wchar_t * restrict pwc, const char * restrict s, size_t n);

DESCRIPTION    [Toc]    [Back]

     The mbtowc() usually converts the multibyte character pointed by s to the
     wide character, and store it to the wchar_t object pointed by pwc if pwc
     is non-null and s points a valid character.  This function may inspect at
     most n bytes of the array beginning from s.

     In state-dependent encodings, s may point the special sequence bytes to
     change the shift-state.  Although such sequence bytes corresponds to no
     individual wide-character code, the mbtowc() changes its own state by the
     sequence bytes and treats them as if they are a part of the subsequence
     multibyte character.

     Unlike mbrtowc(3), the first n bytes pointed by s need to form an entire
     multibyte character.  Otherwise, this function causes an error.

     Calling any other functions in the Standard C Library (libc, -lc) never
     change the internal state of the mbtowc(), except for calling
     setlocale(3) with changing LC_CTYPE category of the current locale.  Such
     setlocale(3) call causes the internal state of this function to be indeterminate.


     The behaviour of the mbtowc() is affected by LC_CTYPE category of the
     current locale.

     There are special cases:

     s == NULL     mbtowc() initializes its own internal state to an initial
                   state, and determines whether the current encoding is
                   state-dependent.  This function returns 0 if the encoding
                   is state-independent, otherwise non-zero.  In this case,
                   pwc is completely ignored.

     pwc == NULL   mbtowc() executes the conversion as if pwc is non-null, but
                   a result of the conversion is discarded.

     n == 0        In this case, the first n bytes of the array pointed by s
                   never form a complete character.  Thus, the mbtowc() always
                   fails.

RETURN VALUES    [Toc]    [Back]

     In the usual cases, the mbtowc() returns:

     0             s points a null byte ('\0').

     positive      number of bytes for the valid multibyte character pointed
                   by s.  There is no cases that the value returned is greater
                   than the value of MB_CUR_MAX macro.

     -1            s points an invalid or an incomplete multibyte character.
                   The mbtowc() also sets errno to indicate the error.

     In the case that s is equal to NULL, the mbtowc() returns:

     0           The current encoding is state-independent.

     non-zero    The current encoding is state-dependent.

ERRORS    [Toc]    [Back]

     The mbtowc() may causes an error in the following case:

     [EILSEQ]           s points an invalid or incomplete multibyte character.

SEE ALSO    [Toc]    [Back]

     mblen(3), mbrtowc(3), setlocale(3)

STANDARDS    [Toc]    [Back]

     The mbtowc() function conforms to ANSI X3.159-1989 (``ANSI C'').  The
     restrict qualifier is added at .

BSD                            February 3, 2002                            BSD