mbstowcs() -- convert multibyte string to wide character string

SYNOPSIS

#include <stdlib.h>

size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n);

The mbstowcs() function converts the multibyte string addressed by s into the corresponding UNICODE string. It stores up to n wide characters in pwcs. It stops conversion after encountering and storing a null character.

PARAMETERS

pwcs: Is the address of an array of wide characters, type wchar_t, to receive the UNICODE equivalent of multibyte string s.
s: Points to a null-terminated multibyte string to be converted to UNICODE.
n: Is the maximum number of characters to convert and store in pwcs.

RETURN VALUES

If successful, mbstowcs() returns the number of multibyte characters it converted, not including the terminating null character. If s is a null pointer or points to a null character, mbstowcs() returns zero. If mbstowcs() encounters an invalid multibyte sequence, it returns -1.