DragonFly On-Line Manual Pages

Search: Section:  

MBTOWC(3)             DragonFly Library Functions Manual             MBTOWC(3)


NAME

     mbtowc, mbtowc_l -- convert a character to a wide-character code


LIBRARY

     Standard C Library (libc, -lc)


SYNOPSIS

     #include <stdlib.h>

     int
     mbtowc(wchar_t * restrict wcharp, const char * restrict mbchar,
         size_t nbytes);

     #include <xlocale.h>

     int
     mbtowc_l(wchar_t * restrict wcharp, const char * restrict mbchar,
         size_t nbytes, locale_t locale);


DESCRIPTION

     The mbtowc() and mbtowc_l() functions convert a multibyte character
     mbchar into a wide character according to the current conversion state,
     and stores the result in the object pointed to by wcharp.  Up to nbytes
     bytes are examined.

     A call with a null mbchar pointer returns nonzero if the current encoding
     requires shift states, zero otherwise; if shift states are required, the
     shift state is reset to the initial state.

     The mbtowc_l() function takes an explicit locale argument, whereas the
     mbtowc() function uses the current global or per-thread locale.


RETURN VALUES

     If mbchar is NULL, the mbtowc() and mbtowc_l() functions return nonzero
     if shift states are supported, zero otherwise.

     Otherwise, if mbchar is not a null pointer, mbtowc() and mbtowc_l()
     either return 0 if mbchar represents the null wide character, or return
     the number of bytes processed in mbchar, or return -1 if no multibyte
     character could be recognized or converted.  In this case, mbtowc()'s and
     mbtowc_l()'s internal conversion states are undefined.


ERRORS

     The mbtowc() and mbtowc_l() functions will fail if:

     [EILSEQ]           An invalid multibyte sequence was detected.

     [EINVAL]           The internal conversion state is invalid.


SEE ALSO

     btowc(3), mbintowcr(3), mblen(3), mbrtowc(3), mbstowcs(3), multibyte(3),
     utf8towcr(3), wctomb(3), xlocale(3)


STANDARDS

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

DragonFly 4.3                  December 26, 2013                 DragonFly 4.3

Search: Section: