mbtowc(), mbtowc_l()

convert multibyte character to wide character 

Function

SYNOPSIS

#include <stdlib.h>

int mbtowc(wchar_t *pwc, const char *s, size_t n);

int mbtowc_l(wchar_t *pwc, const char *s, size_t n, locale_t locale);

DESCRIPTION

The mbtowc() and mbtowc_l() functions convert the multibyte character addressed by s into the corresponding UNICODE character.

mbstowcs_l() behaves in the same way as mbstowcs() 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

pwc 

Is the address of a wide character, type wchar_t, to receive the UNICODE equivalent of s.

s 

Points to the multibyte character to be converted to UNICODE.

n 

Is the maximum width, in bytes, for which to scan s for a valid multibyte sequence. Regardless of the value of n, no more than MB_CUR_MAX (or MB_CUR_MAX_L) bytes are examined.

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

If successful, mbtowc() and mbtowc_l() return the length, in bytes, of the multibyte character for which it found a UNICODE equivalent. If s is null or points to a null character, mbtowc() and mbtowc_l() return zero. If no valid multibyte sequence is found at s, mbtowc() and mbtowc_l() return -1.

CONFORMANCE

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

mbtowc_l() conforms to IEEE Std 1003.1-2008 'POSIX.1'

MULTITHREAD SAFETY LEVEL

MT-Safe, with exceptions.

The mbtowc() function is MT-Safe as long as no thread calls setlocale() while one of these functions is executing.

The function mbtowc_l() is MT-Safe as long as no thread calls freelocale() on locale while one of these functions 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(), mbstowcs(), mbstowcs_l(), newlocale(), setlocale(), wctomb(), wctomb_l()

PTC MKS Toolkit 10.5 Documentation Build 40.