mbsrtowcs
Converts a multibyte character string to a corresponding wide characters string. A more secure version of this function is available; see mbsrtowcs.
size_t mbsrtowcs( wchar_t *wcstr, const char **mbstr, sizeof count, mbstate_t *mbstate ); template <size_t size> size_t mbsrtowcs( wchar_t (&wcstr)[size], const char **mbstr, sizeof count, mbstate_t *mbstate ); // C++ only
The mbsrtowcs function converts a string of multibyte characters, beginning in the specified conversion state contained in mbstate, from the values indirect pointed to in mbstr, into the address of wcstr. The conversion will continue for each character until: after a null terminating multibyte character is encountered, when a non corresponding character is encountered or when the next character would exceed the limit contained in count. If mbsrtowcs encounters the multibyte null character ('\0') either before or when count occurs, it converts it to a 16-bit null terminating character and stops.
Thus, the wide character string at wcstr is null-terminated only if mbsrtowcs encounters a multibyte null character during conversion. If the sequences pointed to by mbstr and wcstr overlap, the behavior of mbsrtowcs is undefined. mbsrtowcs is affected by the LC_TYPE category of the current locale.
The mbsrtowcs function differs from mbstowcs, _mbstowcs_l by its restartability. The conversion state is stored in mbstate for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use mbsrlen rather than mbslen, if a subsequent call to mbsrtowcs where used instead of mbstowcs.
If the wcstr argument is NULL, mbsrtombs returns the required size in words of the destination string. If mbstate is null, the internal mbstate_t conversion state is used. If the character sequence wchar does not have a corresponding multibyte character representation, a -1 is returned and the errno is set to EILSEQ.
If mbstr is NULL, the invalid parameter handler is invoked, as described in Parameter Validation. If execution is allowed to continue, this function sets errno to EINVAL and returns -1.
In C++, this function has a template overload that invokes the newer, secure counterpart of this function. For more information, see Secure Template Overloads.
Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
