Share via

mbsrtowcs

  • Article

mbsrtowcs

size_t ``mbsrtowcs``(wchar_t *dst, const char **src, size_t len, mbstate_t *ps);

The function converts the multibyte string beginning at *src to a sequence of wide characters as if by repeated calls of the form:

x = mbrtowc(dst, *src, n, ps != 0 ? ps : &internal)

where n is some value > 0 and internal is an object of type mbstate_t internal to the mbsrtowcs function. At program startup, internal is initialized to the initial conversion state. No other library function alters the value stored in internal.

If dst is not a null pointer, the mbsrtowcs function stores len wide characters , at most, by calls to mbrtowc. The function effectively increments dst by one and *src by x after each call to mbrtowc that stores a converted wide character. After a call that returns zero, mbsrtowcs stores a null wide character at dst and stores a null pointer at *src.

If dst is a null pointer, len is effectively assigned a large value.

The function returns:

  • (``size_t``)-1, if a call to mbrtowc returns (``size_t``)-1, indicating that it has detected an encoding error before completing the next multibyte character.
  • The number of multibyte characters successfully converted, not including the terminating null character.