Guardian Native C Library Calls Reference Manual (G06.29+, H06.08+, J06.03+)

mbtowc(3) Guardian Native C Library Calls Reference Manual
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.
4−94 Hewlett-Packard Company 527192-018