Format
#include <wchar.h>
size_t mbsrtowcs (wchar_t *dst, const char **src, size_t len,
mbstate_t *ps);Language Level: ANSI
Threadsafe: Yes, if ps is not NULL.
Locale Sensitive: The behavior of this function might be affected by the LC_CTYPE category of the current locale. This function might also be affected by the LC_UNI_CTYPE category of the current locale if LOCALETYPE(*LOCALEUCS2) or LOCALETYPE(*LOCALEUTF) is specified on the compilation command. This function is not available when LOCALETYPE(*CLD) is specified on the compilation command. For more information, see Understanding CCSIDs and Locales.
Wide Character Function: See Wide Characters for more information.
Description
This function is the restartable version of mbstowcs().
The mbsrtowcs() function converts a sequence of multibyte characters that begins in the conversion state described by ps from the array indirectly pointed to by src into a sequence of corresponding wide characters. It then stores the converted characters into the array pointed to by dst.
Conversion continues up to and including an ending null character, which is also stored. Conversion will stop earlier in two cases: when a sequence of bytes are reached that do not form a valid multibyte character, or (if dst is not a null pointer) when len wide characters have been stored into the array pointed to by dst. Each conversion takes place as if by a call to mbrtowc() function.
If dst is not a null pointer, the pointer object pointed to by src will be assigned either a null pointer (if conversion stopped due to reaching an ending null character) or the address just past the last multibyte character converted. If conversion stopped due to reaching an ending null character, the initial conversion state is described.
Return Value
If the input string does not begin with a valid multibyte character, an encoding error occurs, the mbsrtowcs() function stores the value of the macro EILSEQ in errno, and returns (size_t) -1, but the conversion state will be unchanged. Otherwise, it returns the number of multibyte characters successfully converted, which is the same as the number of array elements modified when dst is not a null pointer.
If a conversion error occurs, errno might be set to ECONVERT.
Example that uses mbsrtowcs()
#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
#include <locale.h>
#define SIZE 10
int main(void)
{
char mbs1[] = "abc";
char mbs2[] = "\x81\x41" "m" "\x81\x42";
const char *pmbs1 = mbs1;
const char *pmbs2 = mbs2;
mbstate_t ss1 = 0;
mbstate_t ss2 = 0;
wchar_t wcs1[SIZE], wcs2[SIZE];
if (NULL == setlocale(LC_ALL, "/qsys.lib/locale.lib/ja_jp939.locale"))
{
printf("setlocale failed.\n");
exit(EXIT_FAILURE);
}
mbsrtowcs(wcs1, &pmbs1, SIZE, &ss1);
mbsrtowcs(wcs2, &pmbs2, SIZE, &ss2);
printf("The first wide character string is %ls.\n", wcs1);
printf("The second wide character string is %ls.\n", wcs2);
return 0;
}
/*******************************************************
The output should be similar to:
The first wide character string is abc.
The second wide character string is Am B.
*******************************************************/Also, see the examples for mbrtowc() — Convert a Multibyte Character to a Wide Character (Restartable).
Related Information