Open System Services Library Calls Reference Manual (G06.29+, H06.08+, J06.03+)

OSS Library Calls (i - m) mbtowc(3)
NAME
mbtowc - Converts a multibyte character to a wide character
LIBRARY
G-series native Guardian processes: $SYSTEM.SYSnn.ZCRTLSRL
G-series native OSS processes: /G/system/sysnn/zcrtlsrl
H-series and J-series native Guardian processes: $SYSTEM.ZDLLnnn.ZCRTLDLL
32-bit H-series and J-series OSS processes: /G/system/zdllnnn/zcrtldll
64-bit H-series and J-series OSS processes: /G/system/zdllnnn/ycrtldll
SYNOPSIS
#include <stdlib.h>
int mbtowc (
wchar_t *pwc,
const char *s,
size_t n);
PARAMETERS
pwc Points to the wide character variable location.
s Points to the multibyte character to be converted.
n Specifies 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.
NOTES
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.
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.
527187-017 Hewlett-Packard Company 4−185