mbstowcs_s, _mbstowcs_s_l

Converts a sequence of multibyte characters to a corresponding sequence of wide characters. Versions of mbstowcs, _mbstowcs_l with security enhancements as described in Security Enhancements in the CRT.

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

Parameters

  • [out] pReturnValue
    The number of characters converted.

  • [out] wcstr
    Address of buffer for the resulting converted wide character string.

  • [in] sizeInWords
    The size of the wcstr buffer in words.

  • [in]mbstr
    The address of a sequence of null terminated multibyte characters.

  • [in] count
    The maximum number of wide characters to store in the wcstr buffer, not including the terminating null, or _TRUNCATE.

  • [in] locale
    The locale to use.

Return Value

Zero if successful, an error code on failure.

Error condition

Return value and errno

wcstr is NULL and sizeInWords > 0

EINVAL

mbstr is NULL

EINVAL

The destination buffer is too small to contain the converted string (unless count is _TRUNCATE; see Remarks below)

ERANGE

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.

Remarks

The 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 wcstr buffer equals count.

The destination string is always null-terminated (even in the case of an error).

If 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.

If mbstowcs_s successfully converts the source string, it puts the size in wide characters of the converted string, including the null terminator, into *pReturnValue (provided 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 wcstr is NULL, count is ignored, and sizeInWords must be 0.

If mbstowcs_s encounters an invalid multibyte character, it puts 0 in *pReturnValue, sets the destination buffer to an empty string, sets errno to EILSEQ, and returns EILSEQ.

If the sequences pointed to by mbstr and wcstr overlap, the behavior of mbstowcs_s is undefined.

Security Note:

Ensure that wcstr and mbstr do not overlap, and that count correctly reflects the number of multibyte characters to convert.

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.

Requirements

Routine

Required header

mbstowcs_s

<stdlib.h>

_mbstowcs_s_l

<stdlib.h>

For additional compatibility information, see Compatibility in the Introduction.

.NET Framework Equivalent

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

See Also

Concepts

Data Conversion

Locale

MultiByteToWideChar

Interpretation of Multibyte-Character Sequences

_mbclen, mblen, _mblen_l

mbtowc, _mbtowc_l

wcstombs, _wcstombs_l

wctomb, _wctomb_l