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

    This function also 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

    This 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.