mbtowc

Name

mbtowc - converts a multibyte sequence to a wide character

Library

libc.lib

Synopsis

#include <stdlib.h>

int mbtowc (wchar_t * restrict dst, const char * restrict src, size_t nbytes);

Return values

If mbchar is NULL, the mbtowc function returns nonzero if shift states are supported, zero otherwise.

Otherwise, if mbchar is not a null pointer, mbtowc either returns 0 if mbchar represents the null wide character, or returns the number of bytes processed in mbchar, or returns -1 if no multibyte character could be recognized or converted. In this case, mbtowc internal conversion state is undefined.

Detailed description

The mbtowc function converts 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 behavior of the mbtowc is affected by LC_CTYPE category of the current locale.

Examples

#include <stdlib.h>
#include <wchar.h>
/* Illustrates how to use mbtowc API */
int example_mbtowc(wchar_t *wc, char *s)
{
 int len;
 /* converting multibyte sequence to a wide-character */
 len = mbtowc(wc, s, MB_CUR_MAX);
 /* checking for error */
 if(len < 0)
 {
        wprintf(L"mbtowc returned error!!\n");
 }
 /* returning no of bytes consumed */
 return (len;);
}

Errors

The mbtowc function will fail if:

[`EILSEQ`]
	An invalid multibyte sequence was detected.
[`EINVAL`]
	The internal conversion state is invalid.

Limitations

The current implementation of mbtowc is not affected by the LC_CTYPE category of the current locale. It works only for UTF8 character set.

Feedback

For additional information or queries on this page send feedback