C in a Nutshell

Name

mbrtowc

Synopsis

Converts a multibyte character to a wide character, and saves the parse state

#include <wchar.h>
size_tmbrtowc( wchar_t * restrict widebuffer, const char * restrict string,
                size_t maxsize, mbstate_t * restrict state );

The mbrtowc() function, like mbtowc(), determines the wide character that corresponds to the multibyte character referenced by the second pointer argument, and stores the result in the location referenced by the first pointer argument. Its additional parameter, a pointer to an mbstate_t object, describes the shift state of a multibyte character sequence in the given encoding. mbrtowc() updates this shift-state object after analyzing the multibyte character in the string, so you can use it in a subsequent function call to interpret the next character correctly. (Hence the additional “r” in the function name, which stands for “restartable.”) If the last argument is a null pointer, mbrtowc() uses an internal, static mbstate_t object.

The third argument is the maximum number of bytes to read for the multibyte character, and the return value is the number of bytes that the function actually read to obtain a valid multibyte character. If the string pointer in the second parameter points to a null character, mbrtowc() returns 0 and sets the parse state object to the initial state. If the string pointer does not point to a valid multibyte character, mbrtowc() returns -1, sets the errno variable to EILSEQ, and leaves the mbstate_t object in an undefined state. ...