Converts a multibyte character to a wide character.
Standard C Library (libc.a)
#include <stdlib.h>int mbtowc ( WideCharacter, String, Number)
wchar_t *WideCharacter;
const char *String;
size_t Number;
The mbtowc subroutine converts a multibyte character to a wide character and returns the number of bytes of the multibyte character.
The mbtowc subroutine determines the number of bytes that comprise the multibyte character pointed to by the String parameter. It then converts the multibyte character to a corresponding wide character and, if the WideCharacter parameter is not a null pointer, places it in the location pointed to by the WideCharacter parameter. If the WideCharacter parameter is a null pointer, the mbtowc subroutine returns the number of converted bytes but does not change the WideCharacter parameter value. If the WideCharacter parameter returns a null value, the multibyte character is not converted.
| Item | Description |
|---|---|
| WideCharacter | Specifies the location where a wide character is to be placed. |
| String | Specifies a multibyte character. |
| Number | Specifies the maximum number of bytes of a multibyte character. |
The mbtowc subroutine returns a value of 0 if the String parameter is a null pointer. The subroutine returns a value of -1 if the bytes pointed to by the String parameter do not form a valid multibyte character before the number of bytes specified by the Number parameter (or fewer) have been processed. It then sets the errno global variable to indicate the error. Otherwise, the number of bytes comprising the multibyte character is returned.
The mbtowc subroutine fails if the following occurs:
| Item | Description |
|---|---|
| EILSEQ | Invalid byte sequence is detected. |