errno_t mbsrtowcs_s( size_t *pReturnValue, wchar_t *wcstr, size_t sizeOfwcstr, const char **mbstr, size_t count, mbstate_t *mbstate ); template <size_t size> errno_t mbsrtowcs_s( size_t *pReturnValue, wchar_t (&wcstr)[size], const char **mbstr, size_t count, mbstate_t *mbstate ); // C++ only
The number of bytes written into wcstr or -1 if an error occurred.[out] wcstr
The resulting converted wide character string's address location.[out] sizeOfwcstr
The size of wcstr in words.[in] mbstr
Indirectly points to the location of the multibyte character string to be converted.[in] count
The number of character to be converted.[in] mbstate
A pointer to an mbstate_t conversion state object.
Returns zero or an errno value if an error occurs.
The mbsrtowcs_s 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 pReturnValue parameter will contain the number of words converted, not including the null terminating null byte (if any), or -1 if an error occurred. 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_s encounters the 8-byte null character ('\0') either before or when count occurs, it converts it to a 16-bit null character (L'\0') and stops.
If the sequences pointed to by mbstr and wcstr overlap, the behavior of mbsrtowcs_s is undefined. mbsrtowcs_s is affected by the LC_TYPE category of the current locale.
The mbsrtowcs_s function differs from mbstowcs_s, _mbstowcs_s_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_s where used instead of mbstowcs_s.
If the wcstr argument is NULL, mbsrtowcs returns the required size in words of the destination string, in the address of pReturnValue. If mbstate is null, the internal mbstate_t conversion state is used. If the character sequence mbchar does not have a corresponding wide character representation, a -1 is returned and the errno is set to EILSEQ.
This function validates its parameters. If a parameter is invalid, the invalid parameter handler is invoked, as described in Parameter Validation. If execution is allowed to continue, this function sets errno to an error code and returns the error code.
In C++, using this function is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see Secure Template Overloads.
The mbsrtowcs function is multithread safe as long as no function in the current thread calls setlocale while this function is executing and the mbstate is null.
Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003