|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here.|
Converts a multibyte character string to a corresponding wide characters string. This function is deprecated because a more secure version is available; see.
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
- [out] wcstr
The resulting converted wide character string's address location.
- [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.
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 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.by its restartability. The conversion state is stored in
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 . 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.
Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.