MBRTOWC(3)               BSD Library Functions Manual               MBRTOWC(3)

NAME
     mbrtowc, mbrtowcl -- convert a character to a wide-character code
     (restartable)

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     ##include <>

     sizet
     mbrtowc(wchart * restrict pwc, const char * restrict s, sizet n,
         mbstatet * restrict ps);

     ##include <>

     sizet
     mbrtowcl(wchart * restrict pwc, const char * restrict s, sizet n,
         mbstatet * restrict ps, localet loc);

DESCRIPTION
     The mbrtowc() function inspects at most n bytes pointed to by s to deter-
     mine the number of bytes needed to complete the next multibyte character.
     If a character can be completed, and pwc is not NUL, the wide character
     which is represented by s is stored in the wchart it points to.

     If s is NUL, mbrtowc() behaves as if pwc was NUL, s was an empty string
     ("") and n was 1.

     The mbstatet argument, ps, is used to keep track of the shift state.  If
     it is NUL, mbrtowc() uses an internal, static mbstatet object, which is
     initialized to the initial conversion state at program startup.

     While the mbrtowc() function uses the current locale, the mbrtowcl()
     function may be passed a locale directly. See xlocale(3) for more infor-
     mation.

RETURN VALUES
     The mbrtowc() functions returns:

     0       The next n or fewer bytes represent the null wide character
             (L'\0').

     >0      The next n or fewer bytes represent a valid character, mbrtowc()
             returns the number of bytes used to complete the multibyte char-
             acter.

     (sizet)-2
             The next n contribute to, but do not complete, a valid multibyte
             character sequence, and all n bytes have been processed.

     (sizet)-1
             An encoding error has occurred.  The next n or fewer bytes do not
             contribute to a valid multibyte character.

ERORS
     The mbrtowc() function will fail if:

     [EILSEQ]           An invalid multibyte sequence was detected.

     [EINVAL]           The conversion state is invalid.

SEE ALSO
     mbtowc(3), multibyte(3), setlocale(3), wcrtomb(3), xlocale(3)

STANDARDS
     The mbrtowc() function conforms to ISO/IEC 9899:1999 (``ISO C99'').

BSD                              April 8, 2004                             BSD