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.

A call with s as a null pointer causes this function to return 0.  The behavior of this function is affected by the LC_CTYPE category of the current locale.  At most n bytes of the array pointed to by s will be examined. 

RETURN VALUES

If s is a null pointer, mbtowc() returns a 0 value.  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 the following is detected:

EILSEQ Invalid character sequence

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

SEE ALSO

mblen(3C), mbstowcs(3C), setlocale(3C), wcstombs(3C), wctomb(3C), attributes(5)

NOTES

The mbtowc() function can be used safely in a multi-thread application, as long as setlocale(3C) is not being called to change the locale. 

SunOS 5.6  —  Last change: 20 Dec 1996