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

mbrtowc(3) Guardian Native C Library Calls Reference Manual
NAME
mbrtowc - Convert a character to a wide-character (restartable)
LIBRARY
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 <wchar.h>
size_t mbrtowc(
wchar_t *s,
const char *s,
size_t n,
mbstate_t *ps
);
PARAMETERS
pwc Points to the wide-character object.
s Points to the character.
n The number of bytes to process.
ps Points to the mbstate_t object.
DESCRIPTION
If s is a null pointer, the mbrtowc() function is equivalent to:
mbrtowc(NULL, "", 1 ps)
In this case, the values of the parameters pwc and n are ignored.
If the s parameter is not a null pointer, the mbrtowc() function inspects at most n bytes begin-
ning at the byte pointed to by s to determines the number of bytes needed to complete the next
character. If the function determines that the next character is completed, it determines the value
of the corresponding wide-character and then, if pwc is not a null pointer, stores that value in the
object pointed to by pwc. If the corresponding wide-charcter is the null wide-character, the
resulting state described is the initial conversion state.
If ps is a null pointer, the mbrtowc() function use its own internal mbstate_t object, which is
initialized at program startup to the initial conversion state. Otherwise the mbstate_t object
pointed to by ps is used to completely describe the current conversion state of the associated
character sequence.
RETURN VALUES
The mbrtowc() function returns the first that applies of these:
0 (zero) If the next n or fewer bytes complete the character that corresponds to the null
wide-character (which is the value stored).
positive If the next n or fewer bytes complete a valid character (which is the value
stored), the value returned is the number of bytes that complete the character.
(size_t)-2 If the next n or fewer bytes contribute to an incomplete but potentially valid
character, and all n bytes have been processed (no value is stored).
4−88 Hewlett-Packard Company 527192-018