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

Chapter 5 399
HP C/iX Library Function Descriptions
wctomb
wctomb
Converts a single wide character value to its multibyte character representation.
Syntax
#include <stdlib.h>
int wctomb(char * s , wchar_t wchar );
Parameters
s A pointer to a character array to which the multibyte character is
returned.
wchar The wide character value to be converted.
Return Values
>0 The length of the multibyte character in bytes.
−1 The
wchar parameter does not point to a valid wide character.
0 The
wchar parameter is a null character.
Description
The wctomb function converts the wide character wchar to multibyte representation and
stores the result in the array pointed to by
s (if s is not a null pointer).
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.
If the value of
wchar is zero, wctomb is left in the initial shift state.
If
s is not a null pointer, wctomb returns −1 if the value of wchar does not correspond to a
valid multibyte character, or returns the number of bytes in the multibyte character
corresponding to the value of
wchar
The value returned cannot be greater than the value of the MB_CUR_MAX macro.
See Also
wchar_t, MB_CUR_MAX, mbtowc(), wcstomb(), mbstowcs(), ANSI C 4.10.7.3