NAME    [Toc]    [Back]

     mbrtowc - converts a multibyte character to a wide character
     (restartable)

LIBRARY    [Toc]    [Back]

     Standard C Library (libc, -lc)

SYNOPSIS    [Toc]    [Back]

     #include <wchar.h>

     size_t
     mbrtowc(wchar_t * restrict pwc, const char * restrict s, size_t n,
             mbstate_t * restrict ps);

DESCRIPTION    [Toc]    [Back]

     The mbrtowc() usually converts the multibyte character pointed by s to
     the wide character, and store the wide character to the wchar_t object
     pointed by pwc if pwc is non-null and s points a valid character.  The
     conversion is taken place with conforming to and changing the conversion
     state described in the mbstate_t object pointed by ps.  This function may
     examine at most n bytes of the array beginning from s.

     If s points a valid character and the character corresponds to a null
     wide character, then the mbrtowc() places the mbstate_t object pointed by
     ps to an initial conversion state.

     Unlike mbtowc(3), the mbrtowc() may accept the byte sequence pointed by s
     not forming complete multibyte character but being possible for a part of
     a valid character.  In this case, this function will accept the all of
     such bytes and save them into the conversion state object pointed by ps.
     They will be used at the subsequent call of this function to restart the
     conversion suspended.

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

     There are the special cases:

     s == NULL     The mbrtowc() sets the conversion state object pointed by
                   ps to an initial state and always return 0.  Unlike
                   mbtowc(3), the value returned does not indicate whether the
                   current encoding of the locale is state-dependent.

                   In this case, The mbrtowc() ignores pwc and n, and is
                   equivalent to the following call:

                   mbrtowc(NULL, "", 1, ps);

     pwc == NULL   The conversion from a multibyte character to a wide character
 is taken place and the conversion state may be
                   affected, but the result wide character is discarded.

     ps == NULL    The mbrtowc() uses its own internal state object to keep
                   the conversion state, instead of ps mentioned in this manual
 page.

                   Calling any other functions in the Standard C Library
                   (libc, -lc) never change the internal state of the
                   mbrtowc(), that is initialized at startup time of the program.

RETURN VALUES    [Toc]    [Back]

     In the usual cases, the mbrtowc() returns:

     0             The next bytes pointed by s forms a null character.

     positive      If s is points an valid character, the mbrtowc() returns
                   the number of bytes consisting the character.

     (size_t)-2    s points the byte sequence which is possible to consist a
                   part of valid multibyte character but incomplete.  When n
                   is at least MB_CUR_MAX, this case can only occur if the
                   array pointed s contains redundant shift sequence.

     (size_t)-1    s points a illegal byte sequence which does not form a
                   valid multibyte character.  In this case, the mbrtowc()
                   sets errno to indicate the error.

ERRORS    [Toc]    [Back]

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

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

     [EINVAL]           ps points an invalid or uninitialized mbstate_t
                        object.

SEE ALSO    [Toc]    [Back]

     mbrlen(3), mbtowc(3), setlocale(3)

STANDARDS    [Toc]    [Back]

     The mbrtowc() function conforms to .  The restrict qualifier is added at
     .

BSD                            February 4, 2002                            BSD