Export (0) Print
Expand All
div
eof
Expand Minimize
1 out of 2 rated this helpful - Rate this topic

mbsrtowcs 

Converts a multibyte character string to a corresponding wide characters string. This function is deprecated because a more secure version is available; see mbsrtowcs.


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

Parameters

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

Returns the number of words successfully converted, not including the null terminating null word (if any), otherwise a -1 if an error occurred.

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 mbstowcs, _mbstowcs_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 where used instead of mbstowcs.

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 Parameter Validation. 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 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

mbsrtowcs

<wchar.h>

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

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.