mbrtowc(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
MBRTOWC(3)              NetBSD Library Functions Manual             MBRTOWC(3)


NAME

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


LIBRARY

     Standard C Library (libc, -lc)


SYNOPSIS

     #include <wchar.h>

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


DESCRIPTION

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

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

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

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

     These are the special cases:

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

                   In this case, mbrtowc() ignores pwc and n, and is equiva-
                   lent to the following call:

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

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

     ps == NULL    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 Standard C Library (libc,
                   -lc) never changes the internal state of mbrtowc(), which
                   is initialized at startup time of the program.


RETURN VALUES

     In the usual cases, mbrtowc() returns:

     0             The next bytes pointed to by s form a nul character.

     positive      If s points to a valid character, mbrtowc() returns the
                   number of bytes in the character.

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

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


ERRORS

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

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

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


SEE ALSO

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


STANDARDS

     The mbrtowc() function conforms to ISO/IEC 9899/AMD1:1995 (``ISO C90,
     Amendment 1'').  The restrict qualifier is added at ISO/IEC 9899:1999
     (``ISO C99'').

NetBSD 5.2                     February 4, 2002                     NetBSD 5.2