INtime SDK Help
mbstowcs, mbstowcs_s

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);


A pointer to a size_t variable which receives the nyuber of characters converted.
The address of a sequence of wide characters.
The number of wide characters which can be fitted into the buffer at wcstr.
The address of a sequence of multibyte characters.
The number of multibyte characters to convert.


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:

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.

Error condition Return value and errno
wcstr is NULL and numchar > 0 EINVAL
mbstr is NULL EINVAL
The destination buffer is too small to contain the converted string (unless count is _TRUNCATE) ERANGE
wcstr is not NULL and sizeInWords == 0 EINVAL


Versions Defined in Include Link to
INtime 3.0
INtime 6.0 for mbstowcs_s
intime/rt/include/stdlib.h stdlib.h clib.lib
See Also