mbsrtowcs, mbsrtowcs_s

1) Converts a null-terminated multibyte character sequence, which begins in the conversion state described by *ps , from the array whose first element is pointed to by * src to its wide character representation. If dst is not null, converted characters are stored in the successive elements of the wchar_t array pointed to by dst . No more than len wide characters are written to the destination array. Each multibyte character is converted as if by a call to mbrtowc . The conversion stops if:

• The multibyte null character was converted and stored. * src is set to null pointer value and *ps represents the initial shift state.
• An invalid multibyte character (according to the current C locale) was encountered. * src is set to point at the beginning of the first unconverted multibyte character.
• the next wide character to be stored would exceed len . * src is set to point at the beginning of the first unconverted multibyte character. This condition is not checked if dst is a null pointer.

2) Same as (1) , except that

• the function returns its result as an out-parameter retval
• if no null character was written to dst after len wide characters were written, then L ' \0 ' is stored in dst[len] , which means len+1 total wide characters are written
• the function clobbers the destination array from the terminating null and until dstsz
• If src and dst overlap, the behavior is unspecified.
• the following errors are detected at runtime and call the currently installed constraint handler function:

• retval , ps , src , or * src is a null pointer
• dstsz or len is greater than RSIZE_MAX/sizeof(wchar_t) (unless dst is null)
• dstsz is not zero (unless dst is null)
• There is no null character in the first dstsz multibyte characters in the * src array and len is greater than dstsz (unless dst is null)

As with all bounds-checked functions, mbsrtowcs_s is only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including <wchar.h> .

1) On success, returns the number of wide characters, excluding the terminating L ' \0 ' , written to the character array. If dst is a null pointer, returns the number of wide characters that would have been written given unlimited length. On conversion error (if invalid multibyte character was encountered), returns ( size_t ) - 1 , stores EILSEQ in errno , and leaves * ps in unspecified state.

2) zero on success (in which case the number of wide characters excluding terminating zero that were, or would be written to dst , is stored in * retval ), non-sero on error. In case of a runtime constraint violation, stores ( size_t ) - 1 in * retval (unless retval is null) and sets dst [ 0 ] to L ' \0 ' (unless dst is null or dstmax is zero or greater than RSIZE_MAX )

#include <stdio.h>
#include <locale.h>
#include <wchar.h>
#include <string.h>
 
void print_as_wide(const char* mbstr)
{
    mbstate_t state;
    memset(&state, 0, sizeof state);
    size_t len = 1 + mbsrtowcs(NULL, &mbstr, 0, &state);
    wchar_t wstr[len];
    mbsrtowcs(&wstr[0], &mbstr, len, &state);
    wprintf(L"Wide string: %ls \n", wstr);
    wprintf(L"The length, including L'\\0': %zu\n", len);
}
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    print_as_wide(u8"z\u00df\u6c34\U0001f34c"); // u8"zß水🍌"
}

Wide string: zß水🍌
The length, including L'\0': 5