mbtowc(3) - NetBSD Manual Pages

MBTOWC(3)               NetBSD Library Functions Manual              MBTOWC(3)


NAME

     mbtowc -- converts a multibyte character to a wide character


LIBRARY

     Standard C Library (libc, -lc)


SYNOPSIS

     #include <stdlib.h>

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


DESCRIPTION

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

     In state-dependent encodings, s may point to the special sequence bytes
     to change the shift-state.  Although such sequence bytes correspond to no
     individual wide-character code, 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 to by s need to form an
     entire multibyte character.  Otherwise, this function causes an error.

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

     The behaviour of mbtowc() is affected by the 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 to by
                   s never form a complete character.  Thus, the mbtowc()
                   always fails.


RETURN VALUES

     Normally, the mbtowc() returns:

     0             s points to a nul byte (`\0').

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

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

     When s is equal to NULL, mbtowc() returns:

     0           The current encoding is state-independent.

     non-zero    The current encoding is state-dependent.


ERRORS

     mbtowc() may cause an error in the following case:

     [EILSEQ]           s points to an invalid or incomplete multibyte charac-
                        ter.


SEE ALSO

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


STANDARDS

     The mbtowc() function conforms to ANSI X3.159-1989 (``ANSI C89'').  The
     restrict qualifier is added at ISO/IEC 9899:1999 (``ISO C99'').

NetBSD 5.1                     February 3, 2002                     NetBSD 5.1