NAME

mbtowc − Converts a multibyte character to a wide character

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include <stdlib.h>

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

PARAMETERS

pwcPoints to the wide character variable location. 

sPoints to the multibyte character to be converted. 

nSpecifies the number of bytes in the multibyte character. 

DESCRIPTION

The mbtowc() function converts a multibyte character to a wide character and returns the number of bytes of the multibyte character, which is stored as an output variable. 

In locales with shift-state character encoding, a call to mbtowc() with a null pointer as the s parameter places the function in the initial shift state. A call to mbtowc() with an s parameter that is not a null pointer may change the shift state for subsequent calls to mbtowc(), depending on the character examined.  Changing the LC_CTYPE category of the locale causes the shift state of the function to be indeterminate.  The implementation behaves as though no other function calls the mbtowc() function. 

NOTES

AES Support Level:
Full use.

RETURN VALUES

If the s parameter is not a null pointer, the mbtowc() function returns the following values:

       •When s points to a valid multibyte character other than the null character, mbtowc() returns the number of bytes in the character unless the character contains more than the number of bytes specified by the n parameter. 

       •When s points to a null character, mbtowc() returns a value of 0 (zero). 

       •When s does not point to a valid multibyte character or points to a character having more than the number of bytes expressed by the n parameter, mbtowc() returns a value of -1 and sets errno to indicate the error. 

If the s parameter is a null pointer, the return value depends on whether the character encoding in the current locale is shift-state dependent. 

       •If the character encoding is shift-state dependent, mbtowc() returns a nonzero value. 

       •If the character encoding is not shift-state dependent, mbtowc() returns a value of 0 (zero). 

The return value is never greater than the value specified by the n parameter or the value of MB_CUR_MAX. 

ERRORS

If the following condition occurs, the mbtowc() function sets errno to the corresponding value. 

[EILSEQ]The s parameter points to an invalid multibyte character or a multibyte character with more than n bytes. 

RELATED INFORMATION

Functions: mblen(3), wctomb(3), mbstowcs(3), wcstombs(3).