OSF

NAME

wctomb − Converts a wide character into a multibyte character

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include <stdlib.h>

int wctomb(

char ∗s,

wchar_t wchar) ;

PARAMETERS

s Points to the location where the conversion is stored. 

wchar Specifies the wide character to be converted. 

DESCRIPTION

The wctomb() function converts a wide character into a multibyte character. The wctomb() function stores no more than MB_CUR_MAX bytes. 

The behavior of the wctomb() function is affected by the LC_CTYPE category of the current locale.  In environments with shift-state dependent encoding, calls to the wctomb() function with the wchar parameter set to 0 (zero) put the function in its initial shift state. Subsequent calls with the wchar parameter set to nonzero values alter the state of the function as necessary.  Changing the LC_CTYPE category of the locale causes the shift state of the function to be unreliable. 

The implementation behaves as though no other function calls the wctomb() function. 

NOTES

AES Support Level: Full use

RETURN VALUES

When the s parameter is not a null pointer, the wctomb() function returns a value determined as follows:

• If the wchar parameter corresponds to a valid multibyte character, the wctomb() function returns the number of bytes in the multibyte character. 

• If the wchar parameter does not correspond to a valid multibyte character, the wctomb() function returns -1 and sets errno to indicate the error. 

When the s parameter is a null pointer, the return value depends on the environment in the following way:

• In environments where encoding is not state dependent, wctomb() returns 0 (zero). 

• In environments where encoding is state dependent, wctomb() returns a nonzero value. 

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

ERRORS

If the wctomb() function fails, errno may be set to the following value:

[EINVAL] The wchar parameter does not correspond to a valid multibyte character. 

RELATED INFORMATION

Functions: mblen(3), mbstowcs(3), mbtowc(3), wcstombs(3)