For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.
errno_t mbstowcs_s( size_t *pReturnValue, wchar_t *wcstr, size_t sizeInWords, const char *mbstr, size_t count ); errno_t _mbstowcs_s_l( size_t *pReturnValue, wchar_t *wcstr, size_t sizeInWords, const char *mbstr, size_t count, _locale_t locale ); template <size_t size> errno_t mbstowcs_s( size_t *pReturnValue, wchar_t (&wcstr)[size], const char *mbstr, size_t count ); // C++ only template <size_t size> errno_t _mbstowcs_s_l( size_t *pReturnValue, wchar_t (&wcstr)[size], const char *mbstr, size_t count, _locale_t locale ); // C++ only
The number of characters converted.
Address of buffer for the resulting converted wide character string.
The size of the
wcstr buffer in words.
The address of a sequence of null terminated multibyte characters.
The maximum number of wide characters to store in the
wcstr buffer, not including the terminating null, or _TRUNCATE.
The locale to use.
Zero if successful, an error code on failure.
|Error condition||Return value and |
|The destination buffer is too small to contain the converted string (unless |
If any of these conditions occurs, the invalid parameter exception is invoked as described in Parameter Validation . If execution is allowed to continue, the function returns an error code and sets
errno as indicated in the table.
mbstowcs_s function converts a string of multibyte characters pointed to by
mbstr into wide characters stored in the buffer pointed to by
wcstr. The conversion will continue for each character until one of these conditions is met:
A multibyte null character is encountered
An invalid multibyte character is encountered
The number of wide characters stored in the
The destination string is always null-terminated (even in the case of an error).
count is the special value _TRUNCATE, then
mbstowcs_s converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator.
mbstowcs_s successfully converts the source string, it puts the size in wide characters of the converted string, including the null terminator, into
pReturnValue is not
NULL). This occurs even if the
wcstr argument is
NULL and provides a way to determine the required buffer size. Note that if
count is ignored, and
sizeInWords must be 0.
mbstowcs_s encounters an invalid multibyte character, it puts 0 in
*``pReturnValue, sets the destination buffer to an empty string, sets
EILSEQ, and returns
If the sequences pointed to by
wcstr overlap, the behavior of
mbstowcs_s is undefined.
mbstowcs_s uses the current locale for any locale-dependent behavior;
_mbstowcs_s_l is identical except that it uses the locale passed in instead. For more information, see Locale.
In C++, using these functions 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.
For additional compatibility information, see Compatibility in the Introduction.
Not applicable. To call the standard C function, use
PInvoke. For more information, see Platform Invoke Examples.