NAME

mbtowc - convert a character to a wide-character code

 SYNOPSIS

#include <stdlib.h>

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

 DESCRIPTION

If s is not a null pointer, mbtowc() 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() stores the wide-character code in the object pointed to by pwc.

The behaviour 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.

The implementation will behave as if no function defined in this specification calls mbtowc().

 RETURN VALUE

If s is a null pointer, mbtowc() 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() 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() function may fail if:

[EILSEQ]

Invalid character sequence is detected.

 EXAMPLES

None.

 APPLICATION USAGE

None.

 FUTURE DIRECTIONS

None.

 SEE ALSO

mblen(), mbstowcs(), wctomb(), wcstombs(), <stdlib.h>.