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);

Parameters

pnconv

A pointer to a size_t variable which receives the nyuber of characters converted.

mbstr

The address of a sequence of multibyte characters which have been converted.

numbytes

The size in bytes of the buffer at mbstr.

wcstr

The address of a sequence of wide characters to convert.

count

The number of bytes to convert.

Remarks

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:

• A null wide character is encountered
• A wide character that cannot be converted is encountered
• The number of bytes stored in the mbstr buffer equals count.

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.

Requirements