INtime SDK Help
wcstombs, wcstombs_s

Converts a sequence of wide characters to a corresponding sequence of multibyte characters.

#include <stdlib.h>

size_t wcstombs(char *mbstr, const wchar_t *wcstr, size_t count);
errno_t wcstombs_s(size_t *pnconv, char *mbstr, size_t numchar, const wchar_t *wcstr, size_t count);


A pointer to a size_t variable which receives the nyuber of characters converted.
The address of a sequence of multibyte characters which have been converted.
The size in bytes of the buffer at mbstr.
The address of a sequence of wide characters to convert.
The number of bytes to convert.


If wcstombs encounters the wide-character null, either before or when count occurs, it converts it to the multibyte null character (a 16-bit 0) and stops. Thus, the multibyte character string at mbstr is null-terminated only if wcstombs encounters a wide-character null character during conversion. If the sequences pointed to by wcstr and mbstr overlap, the behavior of wcstombs is undefined.

The wcstombs_s function converts a string of wide characters pointed to by wcstr into multibyte characters stored in the buffer pointed to by mbstr. The conversion will continue for each character until one of these conditions is met:

The destination string is always null-terminated (even in the case of an error).

If count is the special value _TRUNCATE, then wcstombs_s converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator.

If wcstombs_s successfully converts the source string, it puts the size in bytes of the converted string, including the null terminator, into *pnumconv (provided pnumconv is not NULL). This occurs even if the mbstr argument is NULL and provides a way to determine the required buffer size. Note that if mbstr is NULL, count is ignored.

Return Values

wcstombs returns the number of converted multibyte characters, excluding the wide-character null character.

wcstombs_s returns 0 on success, or an code on failure.

Error condition Retrun value and errno
mbstr is NULL and sizeInBytes > 0 EINVAL
wcstr is NULL EINVAL
The destination buffer is too small to contain the converted string (unless count is _TRUNCATE) ERANGE


Versions Defined in Include Link to
INtime 3.0
INtime 6.0 (for wcstombs_s)
intime/rt/include/stdlib.h stdlib.h clib.lib
See Also