Click above to get retro games delivered to your door ever month!

Synopsis:
    #include <wchar.h>
    size_t wcsrtombs( char *dst,
             const wchar_t **src,
             size_t n, mbstate_t *ps );
    #include <wchar.h>
    size_t _fwcsrtombs( char __far *dst,
            const wchar_t __far * __far *src,
            size_t n, mbstate_t __far *ps );

Description:
    The wcsrtombs function converts a sequence of wide characters from the
    array indirectly pointed to by src into a sequence of corresponding
    multibyte characters that begins in the shift state described by ps,
    which, if dst is not a null pointer, are then stored into the array
    pointed to by dst.  Conversion continues up to and including a
    terminating null wide character, but the terminating null character
    (byte) will not be stored.  Conversion will stop earlier in two cases:
     when a code is reached that does not correspond to a valid multibyte
    character, or (if dst is not a null pointer) when the next multibyte
    character would exceed the limit of len total bytes to be stored into
    the array pointed to by dst.  Each conversion takes place as if by a
    call to the  wcrtomb 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
    a terminating null wide character) or the address just past the last
    wide character converted.  If conversion stopped due to reaching a
    terminating null wide character and if dst is not a null pointer, the
    resulting state described will be the initial conversion state.

    The _fwcsrtombs function is a data model independent form of the
    wcsrtombs function that accepts far pointer arguments.  It is most
    useful in mixed memory model applications.

    The restartable multibyte/wide string conversion functions differ from
    the corresponding internal-state multibyte string functions (  mbstowcs
    and  wcstombs) in that they have an extra argument, ps, of type pointer
    to  mbstate_t that points to an object that can completely describe the
    current conversion state of the associated multibyte character sequence.
     If ps is a null pointer, each function uses its own internal  mbstate_t
    object instead.  You are guaranteed that no other function in the
    library calls these functions with a null pointer for ps, thereby
    ensuring the stability of the state.

    Also unlike their corresponding functions, the conversion source
    argument, src, has a pointer-to-pointer type.  When the function is
    storing conversion results (that is, when dst is not a null pointer),
    the pointer object pointed to by this argument will be updated to
    reflect the amount of the source processed by that invocation.

    If the encoding is state-dependent, on entry each function takes the
    described conversion state (either internal or pointed to by ps) as
    current and then, if the destination pointer, dst, is not a null
    pointer, the conversion state described by the pointed-to object is
    altered as needed to track the shift state of the associated multibyte
    character sequence.  For encodings without state dependency, the pointer
    to the  mbstate_t argument is ignored.

Returns:
    If the first code is not a valid wide character, an encoding error
    occurs:  The wcsrtombs 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 bytes in the resulting
    multibyte characters sequence, which is the same as the number of array
    elements modified when dst is not a null pointer.


Example:
    #include <stdio.h>
    #include <wchar.h>
    #include <mbctype.h>
    #include <errno.h>

    const wchar_t wc[] = {
        0x0020,
        0x002e,
        0x0031,
        0x0041,
        0x3000,     /* double-byte space */
        0xff21,     /* double-byte A */
        0x3048,     /* double-byte Hiragana */
        0x30a3,     /* double-byte Katakana */
        0xff61,     /* single-byte Katakana punctuation */
        0xff66,     /* single-byte Katakana alphabetic */
        0xff9f,     /* single-byte Katakana alphabetic */
        0x720d,     /* double-byte Kanji */
        0x0000
    };

    void main()
      {
        int         i;
        size_t      elements;
        wchar_t     *src;
        char        mb[50];
        mbstate_t   pstate;


        _setmbcp( 932 );
        src = wc;
        elements = wcsrtombs( mb, &src, 50, &pstate );
        if( errno == EILSEQ ) {
          printf( "Error in wide character string\n" );
        } else {
          for( i = 0; i < elements; i++ ) {
            printf( "0x%2.2x\n", mb[i] );
          }
        }
      }

    produces the following:

    0x20
    0x2e
    0x31
    0x41
    0x81
    0x40
    0x82
    0x60
    0x82
    0xa6
    0x83
    0x42
    0xa1
    0xa6
    0xdf
    0xe0
    0xa1

Classification:
    wcsrtombs is ANSI, _fwcsrtombs is not ANSI, wcsrtombs is ANSI

Systems:
     wcsrtombs - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

    _fwcsrtombs - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

See Also:
    _mbccmp, _mbccpy, _mbcicmp, _mbcjistojms, _mbcjmstojis, _mbclen,
    _mbctohira, _mbctokata, _mbctolower, _mbctombb, _mbctoupper, mblen,
    mbrlen, mbrtowc, mbsrtowcs, mbstowcs, mbtowc, sisinit, wcrtomb,
    wcstombs, wctob, wctomb