Converts a sequence of multibyte characters to a sequence of wide characters, as determined by the current locale; stores the resulting wide-character string at the specified address.

#include <stdlib.h>

size_t mbstowcs(wchar_t *wcstr, const char *mbstr, size_t count);
errno_t mbstowcs_s(size_t *pnconv, wchar_t *wcstr, size_t numchar, const char *mbstr, size_t count);

Parameters

Remarks

If mbstowcs encounters the null character \0 either before or when count occurs, it converts the null character to a wide-character null and stops. Thus, the wide-character string at wcstr is null-terminated only if it encounters a null character during conversion.

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

The result is similar to a series of calls to mbtowc.

The mbstowcs_s function is a more secture version of mbstowcs. It converts a string of multibyte characters at mbstr into wide characeters in the buffer at wcstr. The conversion continues until one of the following 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 will convert as much of the string as will fit in the destination buffer, while still leaving room for the null terminator,

If mbstowcs_s successfully converts the source string, it puts the sie in wide characters, including the null terminator, into *nconv (providing that pnconv is not NULL). This occurs even if the wcstr argument is NULL, providing a way to determine the required size of the converted string. Note that if wcstr is NULL then numchar must be 0 and count is ignored.

Return Values

mbstowcs returns the number of converted multibyte characters or 0 if the wide-character string is not null-terminated.

mbstowcs_s returns 0 on success, or an error code on failure.

Requirements