Tribblix: manual page: mbtowc.3c

MBTOWC(3C) Standard C Library Functions MBTOWC(3C)

NAME

mbtowc, mbtowc_l - convert a character to a wide-character code

SYNOPSIS

#include <stdlib.h>

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

#include <stdlib.h>
#include <xlocale.h>

int mbtowc_l(wchar_t *restrict pwc, const char *restrict s, size_t n,
locale_t loc);

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.

The function mbtowc_l() behaves identically to mbtowc(), except
instead of using the current locale, it uses the locale as specified
by loc.

RETURN VALUES

If s is a null pointer, these functions return 0. If s is not a null
pointer, they return 0 (if s points to the null byte), the number of
bytes that constitute the converted character (if the next n or fewer
bytes form a valid character), or -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() and mbtowc_l() functions may fail if:

EILSEQ
Invalid character sequence is detected.