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

    Format

      #include  <stdlib.h>

      size_t mbstowcs  (wchar_t *pwcs, const char *s, size_t n);

1  –  Arguments

 pwcs

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

 s

    A pointer to the array of multibyte characters.

 n

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

2  –  Description

    The mbstowcs function converts a sequence of multibyte characters
    from the array pointed to by s to a sequence of wide-character
    codes that are stored into the array pointed to by pwcs, up to a
    maximum of n codes.

    This function is affected by the LC_CTYPE category of the
    program's current locale. If copying takes place between objects
    that overlap, the behavior is undefined.

3  –  Return Values

    x                  The number of array elements modified or
                       required, not included any terminating zero
                       code. The array will not be zero-terminated
                       if the value returned is n. If pwcs is the
                       NULL pointer, mbstowcs returns the number
                       of elements required for the wide-character
                       array.
    (size_t) -1        Indicates that an error occurred. The function
                       sets errno to EILSEQ - Invalid character
                       detected.