Converts a sequence of multibyte characters to a sequence of
    corresponding wide-character codes.

    Format

      #include  <wchar.h>

      size_t mbsrtowcs  (wchar_t *dst, const char **src, size_t len,
                        mbstate_t *ps);

1  –  Function Variants

    The mbsrtowcs function has variants named _mbsrtowcs32 and
    _mbsrtowcs64 for use with 32-bit and 64-bit pointer sizes,
    respectively.

2  –  Arguments

 dst

    A pointer to the destination array containing the resulting
    sequence of wide-character codes.

 src

    An address of the pointer to an array containing a sequence of
    multibyte characters to be converted.

 len

    The maximum number of wide character codes that can be stored in
    the array pointed to by dst.

 ps

    A pointer to the mbstate_t object. If a NULL pointer is
    specified, the function uses its internal mbstate_t object.
    mbstate_t is an opaque datatype intended to keep the conversion
    state for the state-dependent codesets.

3  –  Description

    The mbsrtowcs function converts a sequence of multibyte
    characters, beginning in the conversion state described by the
    object pointed to by ps, from the array indirectly pointed to by
    src, into a sequence of corresponding wide characters.

    If dst is not a NULL pointer, the converted characters are stored
    into the array pointed to by dst. Conversion continues up to and
    including a terminating null character, which is also stored.

    Conversion stops earlier for one of the following reasons:

    o  A sequence of bytes is encountered that does not form a valid
       multibyte character.

    o  If dst is not a NULL pointer, when len codes have been stored
       into the array pointed to by dst.

    If dst is not a NULL pointer, the pointer object pointed to by
    src is assigned either a NULL pointer (if the conversion stopped
    because of reaching a terminating null wide character), or the
    address just beyond the last multibyte character converted (if
    any). If conversion stopped because of reaching a terminating
    null wide character, the resulting state described is the initial
    conversion state.

4  –  Return Values

    n                  The number of multibyte characters
                       successfully converted, sequence, not
                       including the terminating null (if any).
    -1                 Indicates an error. A sequence of bytes that
                       do not form valid multibyte character was
                       encountered. errno is set to EILSEQ; the
                       conversion state is undefined.