C in a Nutshell

Name

mbstowcs

Synopsis

Converts a multibyte string to a wide-character string

#include <stdlib.h>
size_tmbstowcs( wchar_t * restrict dest, const char * restrict src,
                 size_t n );

The mbstowcs() function converts a multibyte string to a wide character string, and returns the number of wide characters in the result, not counting the wide string terminator. The first argument is a pointer to a buffer for the result; the second argument is a pointer to the string of multibyte characters to be converted; the third argument is the maximum number of wide characters to be written to the buffer.

The conversion performed is equivalent to calling mbtowc() for each multibyte character in the original string, beginning in the initial shift state.

Tip

The mbstowcs() function terminates the resulting wide-character string with a null wide character (L'\0') only if it has not yet written the maximum number of wide characters specified by the third argument! If the return value is the same as the specified limit, then the resulting wide string has not been terminated.

If mbstowcs() encounters an invalid multibyte character, it returns -1.

Example

See the example for localeconv() in this chapter.

See Also

mbsrtowcs(), mbtowc(), wcstombs(), wcsrtombs()