mbsrtowcs_s (RL)

Convert a wide character string to its multibyte character string representation. A version of mbsrtowcs with security enhancements as described in Security Enhancements in the CRT.

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

Parameters

[out] pReturnValue

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.

Return Value

Returns zero or an errno value if an error occurs.

Remarks

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.

Exceptions

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.

.NET Framework Equivalent

Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.

Requirements

Routine Required header Compatibility

mbsrtowcs

<wchar.h>

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

See Also

Reference

Data Conversion
Locale
Interpretation of Multibyte-Character Sequences
mbrtowc
mbtowc, _mbtowc_l
mbstowcs_s, _mbstowcs_s_l
mbsinit