mbstowcs(), mbstowcs_l()

convert multibyte string to wide character string 

Function

SYNOPSIS

#include <stdlib.h>

size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n);

#include <stdlib.h>

#include <locale.h>

size_t mbstowcs_l(wchar_t *pwcs, const char *s, size_t n, locale_t locale);

DESCRIPTION

The mbstowcs() and mbstowcs_l() functions convert the multibyte string addressed by s into the corresponding UNICODE string. It stores up to n wide characters in pwcs. It stops conversion after encountering and storing a null 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

pwcs 

Is the address of an array of wide characters, type wchar_t, to receive the UNICODE equivalent of multibyte string s.

s 

Points to a null-terminated multibyte string to be converted to UNICODE.

n 

Is the maximum number of characters to convert and store in pwcs.

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, mbstowcs() and mbstowcs_l() return the number of multibyte characters it converted, not including the terminating null character. If s is a null pointer or points to a null character, mbstowcs() returns zero. If mbstowcs() or mbstowcs_l() encounters an invalid multibyte sequence, they returns -1.

CONFORMANCE

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

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

MULTITHREAD SAFETY LEVEL

MT-Safe, with exceptions.

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

The function mbstowcs_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(), mbtowc(), mbtowc_l(), newlocale(), setlocale(), wcstombs(), wcstombs_l()

PTC MKS Toolkit 10.5 Documentation Build 40.