NAME

wctomb - convert a wide-character code to a character

 SYNOPSIS

#include <stdlib.h>

int wctomb(char *s, wchar_t wchar);

 DESCRIPTION

The wctomb() function determines the number of bytes needed to represent the character corresponding to the wide-character code whose value is wchar (including any change in the shift state). It stores the character representation (possibly multiple bytes and any special bytes to change shift state) in the array object pointed to by s (if s is not a null pointer). At most {MB_CUR_MAX} bytes are stored. If wchar is 0, wctomb() is left in the initial shift state.

The behaviour of this function is affected by the LC_CTYPE category of the current locale. For a state-dependent encoding, this function is placed into its initial state by a call for which its character pointer argument, s, is a null pointer. Subsequent calls with s as other than a null pointer cause the internal state of the function to be altered as necessary. A call with s as a null pointer causes this function to return a non-zero value if encodings have state dependency, and 0 otherwise. Changing the LC_CTYPE category causes the shift state of this function to be indeterminate.

The implementation will behave as if no function defined in this document calls wctomb().

 RETURN VALUE

If s is a null pointer, wctomb() returns a non-zero or 0 value, if character encodings, respectively, do or do not have state-dependent encodings. If s is not a null pointer, wctomb() returns -1 if the value of wchar does not correspond to a valid character, or returns the number of bytes that constitute the character corresponding to the value of wchar.

In no case will the value returned be greater than the value of the MB_CUR_MAX macro.

 ERRORS

No errors are defined.

 EXAMPLES

None.

 APPLICATION USAGE

None.

 FUTURE DIRECTIONS

None.

 SEE ALSO

mblen(), mbtowc(), mbstowcs(), wcstombs(), <stdlib.h>.

DERIVATION

Derived from the ANSI C standard.