mbrtowc()

Converts a multibyte-encoded character to a wide character.

  #include <wchar.h>
  
  int mbrtowc(wchar_t *pwc,
  
  const char *s, size_t n, mbstate_t * ps);    

pwc

A pointer to a wide character in which to store the result.

s

A pointer to the multibyte string to convert.

n

The maximum number of bytes at s with which to form a multibyte character.

ps

The current state of conversion. Ignored if the encoding scheme is non-modal.

This function translates a multibyte character to a wchar_t character according to the encoding specified in the LC_CTYPE component of the current locale. This function operates identically to mbtowcs() except that it has an additional parameter of type mbstate_t*, which is ignored if the multibyte encoding scheme is non-modal.

If s is a null pointer, this call is equivalent to

mbrtowc(NULL, "", 1, ps);

In other words, the function treats s as an empty multibyte string and ignores the pwc and n arguments. Such a call also has the effect of resetting the conversion state.

If s is not a null pointer, the function examines at most n bytes starting with the byte pointed to by s to determine how many bytes are needed to complete a valid encoding of a Unicode character. If the number of bytes that make up a complete, valid character is less than or equal to n and pwc is not a null pointer, the function converts the multibyte character, pointed to by s to a character of type wchar_t using the encoding scheme specified in the LC_CTYPE component of the current locale. It stores this wide character at the location pointed to by pwc.

The function returns one of these values:

• Zero if s points to a nul character.
• The number of bytes in the complete multibyte character that was converted to a wide character if s points to a complete, valid multibyte character of n or fewer bytes. The wide character is stored in the location referred to by pwc if it is not NULL.
• -2 if the next n bytes pointed to by s constitute an incomplete but potentially valid multibyte character. No wide character is stored at the location referred to by pwc.
• -1 if the next n bytes pointed to by s do not constitute a complete, valid multibyte character. The function stores EILSEQ in errno. No wide character is stored at the location referred to by pwc.