wcstombs(), wcstombs_l()

convert wide character string to multibyte string 

Function


SYNOPSIS

#include <stdlib.h>

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

#include <locale.h>

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


DESCRIPTION

The wcstombs() function converts a sequence of codes that correspond to multibyte characters from the array pointed to by pwcs into a sequence of multibyte characters that begins in the initial shift state. Then, wcstombs() stores these multibyte characters into the array pointed to by s. If a multibyte character exceeds the limit of n total bytes or if a NULL character is stored, wcstombs() stops. Each code is converted as if by a call to the wctomb() function, except that the shift state of the wctomb() function is not affected.

No more than n bytes are modified in the array pointed to by s. If copying takes place between objects that overlap, the behavior is undefined.

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

Points to the sequence of multibyte characters.

pwcs 

Points to the sequence of wide characters.

Is the maximum number of bytes that can be stored in the multibyte string.

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 wcstombs() and wcstombs_l() functions return the number of bytes written into s, excluding the terminating NULL, if it was able to convert the wide character string. If the pwcs string is NULL, the wcstombs() and wcstombs_l() functions return the required size of the destination string. If the conversion could not be performed, -1 is returned.


CONFORMANCE

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

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


MULTITHREAD SAFETY LEVEL

MT-Safe, with exceptions.

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

The function wcstombs_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:
newlocale(), setlocale(), wctomb(), wctomb_l()


PTC MKS Toolkit 10.3 Documentation Build 39.