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

Synopsis:
    #include <wchar.h>
    size_t mbsrtowcs( wchar_t *dst,
                   const char **src,
                   size_t len, mbstate_t *ps );
    #include <mbstring.h>
    size_t _fmbsrtowcs( wchar_t __far *dst,
             const char __far * __far *src,
             size_t len, mbstate_t __far *ps );

Description:
    The mbsrtowcs function converts a sequence of multibyte characters that
    begins in the shift state described by ps from the array indirectly
    pointed to by src into a sequence of corresponding wide characters,
    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 character, but the terminating null wide character will
    not be stored.  Conversion will stop earlier in two cases:  when a
    sequence of bytes is reached that does not form a valid multibyte
    character, or (if dst is not a null pointer) when len codes have been
    stored into the array pointed to by dst.  Each conversion takes place as
    if by a call to the  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
    a terminating null character) or the address just past the last
    multibyte character converted.  If conversion stopped due to reaching a
    terminating null character and if dst is not a null pointer, the
    resulting state described will be the initial conversion state.

    The _fmbsrtowcs function is a data model independent form of the
    mbsrtowcs 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 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.


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

    const char chars[] = {
        ' ',
        '.',
        '1',
        'A',
        0x81,0x40, /* double-byte space */
        0x82,0x60, /* double-byte A */
        0x82,0xA6, /* double-byte Hiragana */
        0x83,0x42, /* double-byte Katakana */
        0xA1,      /* single-byte Katakana punctuation */
        0xA6,      /* single-byte Katakana alphabetic */
        0xDF,      /* single-byte Katakana alphabetic */
        0xE0,0xA1, /* double-byte Kanji */
        0x00
    };

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


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

    produces the following:

    0x0020
    0x002e
    0x0031
    0x0041
    0x3000
    0xff21
    0x3048
    0x30a3
    0xff61
    0xff66
    0xff9f
    0x720d

Classification:
    mbsrtowcs is ANSI, _fmbsrtowcs is not ANSI

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

    _fmbsrtowcs - 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, mbstowcs, mbtowc, sisinit, wcrtomb, wcsrtombs,
    wcstombs, wctob, wctomb