wcrtomb(), wcrtomb_l(), c16rtomb(), c16rtomb_l(), c32rtomb(), c32rtomb_l()

convert wide character to multibyte character (restartable) 

Function


SYNOPSIS

#include <wchar.h>

size_t wcrtomb(char *s, wchar_t wc, mbstate_t *ps);

#include <uchar.h>

size_t c16rtomb(char *s, char16_t wc, mbstate_t *ps);

size_t c32rtomb(char *s, char32_t wc, mbstate_t *ps);

#include <wchar.h>

#include <locale.h>

size_t wcrtomb_l(char *s, wchar_t wc, mbstate_t *ps, locale_t locale);

#include <uchar.h>

#include <locale.h>

size_t c16rtomb_l(char *s, char16_t wc, mbstate_t *ps, locale_t locale);

size_t c32rtomb_l(char *s, char32_t wc, mbstate_t *ps, locale_t locale);


DESCRIPTION

The wcrtomb(), c16rtomb() and c32rtomb() functions store a multibyte sequence representing the wide character wc, including any necessary shift sequences, to the character array s, storing a maximum of MB_CUR_MAX bytes.

If s is a null pointer, the wcrtomb() function is equivalent to the call:

wcrtomb(buf, L'\0', ps)

where buf is an internal buffer.

If s is not a null pointer, the wcrtomb() function determines the number of bytes needed to represent the character that corresponds to the wide character given by wc (including any shift sequences), and stores the resulting bytes in the array pointed to by s. At most MB_CUR_MAX (or MB_CUR_MAX_L bytes are stored. If wc is a null wide character, a null byte is stored, preceded by any shift sequence needed to restore the initial shift state. The resulting state described is the initial conversion state.

If the specified state pointer is null, the wcrtomb() function uses its own internal mbstate_t object, which is initialized at program startup to the initial conversion state. Otherwise, the specified mbstate_t object is used to completely describe the current conversion state of the associated character sequence.

The behavior of this function is affected by the LC_CTYPE category of the current locale.

wcrtomb_l() c16rtomb_l() and c32rtomb_l() functions behave in the same way as wcrtomb(), c16rtomb() and c32rtomb() without the _l suffix, but uses the specified locale rather than the global or per-thread locale. A locale_t is returned by newlocale().

As certain multibyte characters may only be represented by a series of 16-bit characters, the c16rtomb() may need to invoked multiple times before a multibyte sequence is returned.


PARAMETERS

s 

Is the buffer used to receive the converted character. This can be a null pointer if no conversion is desired.

wc 

Is the wide character to convert.

ps 

Is the conversion state. If this is null, an internal mbstate_t object is used.

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 wcrtomb(), c16rtomb(), c32rtomb(), wcrtomb_l() c16rtomb_l(), and c32rtomb_l() functions return the number of bytes stored in the array object (including any shift sequences). This value may be 0, e.g. when processing the first char16_t in a surrogate pair. When wc is not a valid wide character, an encoding error occurs. In this case, errno is set to EILSEQ and -1 is returned; the conversion state is undefined.


CONFORMANCE

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

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

c16rtomb(), c16rtomb_l(), c32rtomb(), and c32rtomb_l() conform to ANSI/ISO 9899:2011 'ISO C11'


MULTITHREAD SAFETY LEVEL

MT-Safe, with exceptions.

The function wcrtomb(), c16rtomb() and c32rtomb() are MT-Safe as long as no thread calls setlocale() while these functions are executing and NULL is not passed the ps pointer.

The function wcrtomb_l(), c16rtomb_l() and c32rtomb_l() are MT-Safe as long as no thread calls freelocale() on locale while these functions are executing and NULL is not passed the ps pointer.


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:
mbrlen(), mbrlen_l(), mbrtowc(), mbrtowc_l(), mbsinit(), mbsinit_l(), mbsrtowcs(), mbsrtowcs_l(), newlocale(), setlocale(), wcsrtombs(), wcsrtombs_l()


PTC MKS Toolkit 10.3 Documentation Build 39.