mbsrtowcs, mbsrtowcs_s

 

C

Compiler support

Language

Headers

Type support

Program utilities

Variadic function support

Error handling

Dynamic memory management

Strings library

Algorithms

Numerics

Date and time utilities

Input/output support

Localization support

Concurrency support (C11)

Technical Specifications

Symbol index

 

Strings library

Byte strings

Multibyte strings

Wide strings

 

Null-terminated multibyte strings

Wide/multibyte conversions
mbsinit (C95)
mbstowcsmbstowcs_s (C11) btowc (C95) mbrtowc (C95) mbsrtowcsmbsrtowcs_s (C95)(C11)     mbrtoc8 (C23) c8rtomb (C23) mbrtoc16 (C11) c16rtomb (C11) c32rtomb (C11) mbrtoc32 (C11)	mblen mbtowc wctombwctomb_s (C11) wcstombswcstombs_s (C11) wctob (C95) wcrtombwcrtomb_s (C95)(C11) wcsrtombswcsrtombs_s (C95)(C11) mbrlen (C95)
Types
mbstate_t (C95)

 

Defined in header <wchar.h>
	(1)
size_t mbsrtowcs( wchar_t* dst, const char** src, size_t len, mbstate_t* ps );			(since C95) (until C99)
size_t mbsrtowcs( wchar_t *restrict dst, const char **restrict src, size_t len,                   mbstate_t *restrict ps );			(since C99)
errno_t mbsrtowcs_s( size_t *restrict retval,                      wchar_t *restrict dst, rsize_t dstsz,                      const char **restrict src, rsize_t len,                      mbstate_t *restrict ps );		(2)	(since C11)

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

Parameters

dst	-	pointer to wide character array where the results will be stored
src	-	pointer to pointer to the first element of a null-terminated multibyte string
len	-	number of wide characters available in the array pointed to by dst
ps	-	pointer to the conversion state object
dstsz	-	max number of wide characters that will be written (size of the dst array)
retval	-	pointer to a size_t object where the result will be stored

Return value

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)

Example

Run this code

#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ß水🍌"
}

Output:

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

References

• C11 standard (ISO/IEC 9899:2011):

• 7.29.6.4.1 The mbsrtowcs function (p: 445)

• K.3.9.3.2.1 The mbsrtowcs_s function (p: 648-649)

• C99 standard (ISO/IEC 9899:1999):

• 7.24.6.4.1 The mbsrtowcs function (p: 391)

See also

mbstowcsmbstowcs_s (C11)	converts a narrow multibyte character string to wide string (function)
mbrtowc (C95)	converts the next multibyte character to wide character, given state (function)
wcsrtombswcsrtombs_s (C95)(C11)	converts a wide string to narrow multibyte character string, given state (function)
C++ documentation for mbsrtowcs