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

NAME
     mmbbrrttoowwcc, mmbbrrttoowwccll - convert a character to a wide-character code
     (restartable)

LLIIBBRRAARRYY
     Standard C Library (libc, -lc)

SYNOPSIS
     ##iinncclluuddee <>

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

     ##iinncclluuddee <>

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

DESCRIPTION
     The mmbbrrttoowwcc() 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 NULL, the wide character
     which is represented by s is stored in the wchart it points to.

     If s is NULL, mmbbrrttoowwcc() behaves as if pwc was NULL, 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 NULL, mmbbrrttoowwcc() uses an internal, static mbstatet object, which is
     initialized to the initial conversion state at program startup.

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

RETURN VALUES
     The mmbbrrttoowwcc() 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, mmbbrrttoowwcc()
             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.

EERRRROORRSS
     The mmbbrrttoowwcc() 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 mmbbrrttoowwcc() function conforms to ISO/IEC 9899:1999 (``ISO C99'').

BSD                              April 8, 2004                             BSD