OSF

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 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 environments with shift-state dependent encoding, calls to mbtowc() with the s parameter set to null, places the function in its initial shift state.  Subsequent calls with the s parameter set to nonnull values alter the state of the function as necessary.  Changing the LC_CTYPE  category of the locale causes the shift state of the function to be unreliable. 

The implementation behaves as though no other function calls the mbtowc() function. 

NOTES

AES Support Level:
Full use

RETURN VALUES

When 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 null, 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 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 -1 and sets errno to indicate the error. 

When the s parameter is a null pointer, the return value depends on the environment in which the mbtowc() function is called, as follows:

       •In environments where encoding is not state dependent, mbtowc() returns 0 (zero). 

       •In environments where encoding is state dependent, mbtowc() returns a nonzero value. 

In no case is the return value greater than the value specified by the n parameter or the value of the MB_CUR_MAX macro. 

ERRORS

If the mbtowc() function fails, errno may be set to the following value:

[EINVAL]The s parameter points to an invalid multibyte character. 

RELATED INFORMATION

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