HP C/iX Library Reference Manual (30026-90004)

252 Chapter5
HP C/iX Library Function Descriptions
mbtowc
mbtowc
Converts a single multibyte character to its wide character representation.
Syntax
#include <stdlib.h>
int mbtowc(wchar_t * pwc , const char * s ,size_t n );
Parameters
pwc A pointer to an object of type wchar_t to which the function returns the
converted value.
s A pointer to a multibyte character to be converted.
n An expression of type size_t indicating the number of characters in s to
be examined. This should be no greater than the value of MB_CUR_MAX.
Return Values
>0 The number of bytes that are in the converted multibyte character.
−1 The
s parameter does not point to a valid multibyte character.
0 The
s parameter is a null pointer and multibyte character encodings are
not state-dependent, or
s points to a null character.
Description
If s is not a null pointer, mbtowc determines the number of bytes in the multibyte
character pointed to by
s . It then determines the code for the value of type wchar_t that
corresponds to that multibyte character. (The value of the code corresponding to the null
character is zero.)
If the multibyte character is valid and
pwc is not a null pointer, mbtowc stores the code in
the object pointed to by
pwc . A maximum of n characters are examined, starting at the
character pointed to by
s .
This function retains state information. Multibyte encodings can be state-dependent,
employing "shift characters" to alter the meaning of subsequent characters. The shift state
is persistent between calls to the routines for processing extended character sets unless
the LC_CTYPE category of the locale is changed.
Calling this function with the s argument set to NULL resets the function to its initial state.
When using a NULL pointer to clear the shift state, zero is returned if the multibyte shift
state was previously clear. A nonzero value is returned if the locale-specific shift state was
previously set.
See Also
wchar_t, MB_CUR_MAX, wctomb(), mbstowcs(), wcstombs(), ANSI C 4.10.7.2