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

OSS Library Calls (i - m) mbrtowc(3)
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).
527187-017 Hewlett-Packard Company 4−179