Format
#include <wchar.h>
size_t mbsrtowcs (wchar_t *dest, const char **src,
size_t len, mbstate_t *ps);
Language Level: ANSI 93
mbsrtowcs is a restartable version of mbstowcs, and performs the
same function. It converts the sequence of multibyte characters
from the array indirectly pointed to by src into a
sequence of corresponding wide characters, and then stores the
converted characters in the array pointed to by dest.
Conversion continues up to and including the terminating wchar_t null character. The terminating null wide character is also stored. Conversion stops earlier if a sequence of bytes does not form a valid multibyte character, or when len codes have been stored into the array pointed to by dest. Each conversion takes place as if by a call to the mbrtowc function.
mbsrtowcs assigns the object pointed to by src either a null pointer (if conversion stopped because a terminating null character was reached) or the address just past the last multibyte character converted.
With mbsrtowcs, you can switch from one multibyte string to another. On platforms that support shift states, ps represents the initial shift state of the string (0). If you read in only part of the string, mbsrtowcs sets ps to the string's shift state at the point you stopped. You can then call mbsrtowcs again for that string and pass in the updated ps value to continue reading where you left off.
Note: Because the OS/2 and Windows code pages do not have shift states, the ps parameter is provided only for compatibility with other ANSI/ISO platforms. IBM C and C++ Compilers ignores the value passed for ps.
The behavior of mbsrtowcs is affected by the LC_CTYPE category of the current locale.
Return Value
mbsrtowcs returns the number of multibyte characters
successfully converted, not including the terminating null
character. If dest is a null pointer, the value of len
is ignored and mbsrtowcs returns the number of elements required
for the converted wide characters.
If the input string contains an invalid multibyte character, mbsrtowcs sets errno to EILSEQ and returns (size_t)-1.
Example
This example uses mbsrtowcs to convert the multibyte
characters in the arrays mbs1 and mbs2, and store them in the
arrays wcs1 and wcs2.
#include <wchar.h> #include <stdio.h> #include <stdlib.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, "ja_jp.ibm-932")) {
printf("setlocale failed.\n");
exit(EXIT_FAILURE);
}
mbsrtowcs(wcs1, &pmbs1, SIZE, &ss1);
mbsrtowcs(wcs2, &pmbs2, SIZE, &ss2);
printf("The first character string is %ls.\n", wcs1);
printf("The second character string is %ls.\n", wcs2);
return 0;
/******************************************************
The output should be similiar to:
The first character string is abc.
The second character string is Am B.
******************************************************/
}
![]()
mblen -- Determine Length of Multibyte
Character
mbrlen -- Calculate Length of
Multibyte Character
mbrtowc -- Convert Multibyte Character
to Wide Character
mbsrtowcs -- Convert Multibyte String
to Wide-Character String
mbstowcs -- Convert Multibyte String
to Wide-Character String
setlocale -- Set Locale
wcrtomb -- Convert Wide Character to
Multibyte Character
wcsrtombs -- Convert Wide-Character
String to Multibyte String
<locale.h>
<wchar.h>