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

Format

>     #include <wchar.h>
>     size_t wcsrtombs (char *dest, const wchar_t **src,
>                       size_t len, mbstate_t *ps);

Language Level: ANSI 93
wcsrtombs is a restartable version of wcstombs, and performs the same function. It converts a sequence of wide characters from the array indirectly pointed to by src into a sequence of corresponding multibyte characters and then stores the converted characters into the array pointed to by dest.

Conversion continues up to and including the terminating wchar_t null character.

In both OS/2 and Windows, the terminating wchar_t null character is 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 places as if by a call to the wcrtomb function.

wcsrtombs 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 wide character converted.

With wcsrtombs, you can begin processing a multibyte string, and then another. Once you have begun processing the second string, you may switch back and continue with the first string. 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, wcsrtombs sets ps to the string's shift state at the point you stopped. You can then call wcsrtombs again for that string and pass in the updated ps value to continue reading where you left off.

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. This product ignores the value passed for ps.

The behavior of wcsrtombs is affected by the LC_CTYPE category of the current locale.

Return Value
wcsrtombs returns the number of bytes in the resulting multibyte character sequence pointed to by dest. If dest is a null pointer, the value of len is ignored and wcsrtombs returns the number of elements required for the converted wide characters.

If the input string contains an invalid wide character, wcsrtombs sets errno to EILSEQ and returns (size_t)-1, but the conversion state remains unchanged.

Example
This example uses wcsrtombs to convert two wide-character strings to multibyte character strings.

    #include <stdlib.h>
    #include <stdio.h>
    #include <locale.h>
    #include <wchar.h>

    #define SIZE  20
    #define LOCNAME "ja_jp.ibm-932"

    int main(void)
    {
       wchar_t       wcs1[] = L"abc";
       wchar_t       wcs2[] = L"A\x8142" L"C";
       const wchar_t *pwcs1 = wcs1;
       const wchar_t *pwcs2 = wcs2;
       mbstate_t     ss1 = 0;
       mbstate_t     ss2 = 0;
       char          mb1[SIZE], mb2[SIZE];

       if (NULL == setlocale(LC_ALL, LOCNAME)) {
          printf("Locale \"%s\" could not be loaded\n", LOCNAME);
          exit(1);
       }
       wcsrtombs(mb1, &pwcs1, SIZE, &ss1);
       wcsrtombs(mb2, &pwcs2, SIZE, &ss2);
       printf("The first multibyte string is: <%s>\n", mb1);
       printf("The second multibyte string is: <%s>\n", mb2);
       return 0;

       /**********************************************************
          The output should be similiar to:

          The first multibyte string is: <abc>
          The second multibyte string is: <A BC>
       **********************************************************/
    }

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
wcrtomb -- Convert Wide Character to Multibyte Character
wcstombs -- Convert Wide-Character String to Multibyte String
<wchar.h>