mbtowc(3)                                                     mbtowc(3)

  mbtowc()

  NAME

    mbtowc() - convert character to a wide-character code

  SYNOPSIS

    #include 

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

  DESCRIPTION

    If s is not a null pointer, mbtowc(3) determines the number of the bytes
    that constitute the character pointed to by s. It then determines the
    wide-character code for the value of type wchar_t that corresponds to that
    character. (The value of the wide-character code corresponding to the null
    byte is 0.) If the character is valid and pwc is not a null pointer,
    mbtowc(3) stores the wide-character code in the object pointed to bypwc.

    The behavior of this function is affected by the LC_CTYPE category of the
    current locale. For a state-dependent encoding, this function is placed
    into its initial state by a call for which its character pointer argument,
    s, is a null pointer. Subsequent calls with s as other than a null pointer
    cause the internal state of the function to be altered as necessary. A
    call with s as a null pointer causes this function to return a non-zero
    value if encodings have state dependency, and 0 otherwise. If the
    implementation employs special bytes to change the shift state, these
    bytes do not produce separate wide-character codes, but are grouped with
    an adjacent character. Changing the LC_CTYPE category causes the shift
    state of this function to be indeterminate. At most n bytes of the array
    pointed to by s will be examined.

  RETURN VALUES

    If s is a null pointer, mbtowc(3) returns a non-zero or 0 value, if
    character encodings, respectively, do or do not have state-dependent
    encodings. If s is not a null pointer, mbtowc(3) either returns 0 (if s
    points to the null byte), or returns the number of bytes that constitute
    the converted character (if the next n or fewer bytes form a valid
    character), or returns -1 and may set errno to indicate the error (if they
    do not form a valid character).

    In no case will the value returned be greater than n or the value of the
    MB_CUR_MAX macro.

  ERRORS

    The mbtowc(3) function may fail if:

    [EILSEQ]
        Invalid character sequence is detected.

  SEE ALSO

    mblen(3)

    mbstowcs(3)

    wctomb(3)

    wcstombs(3)

  USAGE NOTES

    The mbtowc function is thread safe.

    The mbtowc function is not async-signal safe.