Converts a multibyte character to its wide-character equivalent.

    Format

      #include  <stdlib.h>

      int mbtowc  (wchar_t *pwc, const char *s, size_t n);

1  –  Arguments

 pwc

    A pointer to the resulting wide-character code.

 s

    A pointer to the multibyte character.

 n

    The maximum number of bytes that comprise the next multibyte
    character.

2  –  Description

    If the character is n or fewer bytes, the mbtowc function
    converts the multibyte character pointed to by s to its wide-
    character equivalent. If the character is invalid or greater than
    n bytes, the function returns -1 to indicate an error.

    If pwc is a NULL pointer and s is not a null pointer, the
    function determines the number of bytes that constitute the
    multibyte character pointed to by s (regardless of the value
    of n).

    This function is affected by the LC_CTYPE category of the
    program's current locale.

3  –  Return Values

    x                  The number of bytes that comprise the valid
                       character pointed to by s.
    0                  If s is either a NULL pointer or a pointer to
                       the null byte.
    -1                 Indicates an error. The function sets errno to
                       EILSEQ - Invalid character detected.