wctomb(), wctomb_l()

convert wide character to multibyte character 

Function


SYNOPSIS

#include <stdlib.h>

int wctomb(char *s, wchar_t wchar);

#include <locale.h>

int wctomb_l(char *s, wchar_t wchar, locale_t locale);


DESCRIPTION

The wctomb() and wctomb_l() functions convert wchar into a multibyte character and stores the result, up to MB_CUR_MAX (or MB_CUR_MAX_L) bytes, in the array object pointed to by s. The behavior of this function is affected by the LC_CTYPE category for the current locale. When wctomb() is called with s as a NULL pointer, if the encoding has a state dependency a non-zero value is returned and the function is placed into its initial state, otherwise 0 is returned. Subsequent calls with s as other than a NULL pointer cause the internal state of the function to be altered as necessary. Changing the LC_CTYPE category causes the shift state of this function to be indeterminate.

wctomb_l() behaves in the same way as wctomb() without the _l suffix, but uses the specified locale rather than the global or per-thread locale. A locale_t is returned by newlocale().


PARAMETERS

s 

Is the address of the multibyte character.

wchar 

Is the wide character to convert.

locale 

Is a locale_t perhaps returned by newlocale() or LC_GLOBAL_LOCALE or 0 for the current thread locale set with uselocale().


RETURN VALUES

The wctomb() and wctomb_l() function returns the number of bytes, never greater than MB_CUR_MAX (or MB_CUR_MAX_L), in the wide character wchar. If wchar is the NULL character then wctomb() and wctomb_l() return 1. If the conversion of wchar is not possible in the current locale, wctomb() and wctomb_l() return -1.


CONFORMANCE

wctomb() conforms to ANSI/ISO 9899:1990 'ISO C90'

wctomb_l() conforms to ANSI/ISO 9899:1999 'ISO C99'


MULTITHREAD SAFETY LEVEL

MT-Safe, with exceptions.

The function wctomb() is MT-Safe as long as no thread calls setlocale() while this function is executing.

The function wctomb_l() is MT-Safe as long as no thread calls freelocale() on locale while this function is executing.


PORTING ISSUES

None.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Functions:
mblen(), mblen_l(), mbtowc(), mbtowc_l(), newlocale(), setlocale(), wcstombs(), wcstombs_l()


PTC MKS Toolkit 10.3 Documentation Build 39.