C Programming/wchar.h/mbrtowc

mbrtowc() function is used for converting the multibyte character to wide character using conversion state.

mbrtowc()

Function of mbrtowc()

mbrtowc() convert the multibyte character to wide character using conversion states

SYNOPSIS of a function mbrtowc():

#include <wchar.h>

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

Description of mbrtowc() function:

Let us consider s is a Null pointer. Then mbrtowc() function can be called as:
mbrtowc(NULL, "", 1, ps);
Here value of pwc and n is ignored.
If s is not NULL, function should inspects mostly n bytes starting from where first s is pointed for the determination of number of bytes that will be needed for the completion of next character and it determines the value of corresponding wide character. And then if pwc is not a null pointer,it stored that value in the object pointed by pwc. If that corresponding wide character is wide null character then whatever is the resulting state described is the initial conversion state.
If the specified state pointer i.e. if ps is a null pointer then mbrtowc() function should use its own mbstate_t object, which shall be initialized to the initial conversion state at the starting of the program. Otherwise mbstate_t object pointed to by ps should be used to describe the current conversion state of the associated character sequence.

Parameter used:

s:

s is used as string whose bytes are to be converted or counted.

n:

n is used for specification of maximum number of bytes for examination.

ps:

ps is the conversion state. If this is null then internal mbstate_t object is used.

Return values:

0:

It returns 0 when the next count or fewer bytes complete the multibyte character that represent a null wide character.

>0:

It returns the value greater than zero i.e. positive value when the next count or fewer bytes complete the valid multibyte character, the value return is the number of bytes that complete the multibyte character.

-1:

It returns -1 when an encoding error occurs, i.e. the next count or fewer bytes don't contribute for complete and valid multibyte character, the errno value will be EILSEQ and the conversion state is confusing as it can be understood in more ways.

-2

It returns -2 when the next count bytes contribute to an incomplete multibyte and all count bytes have been processed.

http://pubs.opengroup.org/onlinepubs/009604499/functions/mbrtowc.html