### mbsrtowcs -- Convert Multibyte String to Wide-Character String

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>