Exportar (0) Imprimir
Expandir todo
Expandir Minimizar
Este tema aún no ha recibido ninguna valoración - Valorar este tema


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 sizeInWords,
   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


[out] pReturnValue

The number of characters converted.

[out] wcstr

The resulting converted wide character string's address location.

[out] sizeInWords

The size of wcstr in words (wide characters).

[in] mbstr

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.

Zero if successful, an error code on failure.

Error condition Return value and errno

wcstr is NULL and sizeInWords > 0


mbstr is NULL


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


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.

The mbsrtowcs_s function converts a string of multibyte characters pointed to by mbstr into wide characters stored in the buffer pointed to by wcstr, using the conversion state contained in mbstate. 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 characters converted equals count.

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

If count is the special value _TRUNCATE, then mbsrtowcs_s converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator.

If mbsrtowcs_s successfully converts the source string, it puts the number of converted wide characters into *pReturnValue (provided pReturnValue is not NULL). If the wcstr argument is NULL, mbsrtowcs_s returns the required size in words (wide characters) of the destination string in *pReturnValue. If mbstate is NULL, the internal mbstate_t conversion state is used. If a character sequence does not have a corresponding wide character representation, *pReturnValue is set to 0, the destination buffer is set to an empty string, and EILSEQ is returned.

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.

Security noteSecurity Note

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

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 were used instead of mbstowcs_s.

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.

Routine Required header Compatibility



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

¿Te ha resultado útil?
(Caracteres restantes: 1500)
Gracias por sus comentarios

Adiciones de comunidad

© 2014 Microsoft. Reservados todos los derechos.