wcstombs

Name

wcstombs - convert a wide character string to a multibyte string

Library

libc.lib

Synopsis

#include <stdlib.h>

size_t wcstombs (char * restrict dst, const wchar_t * restrict src, size_t nbytes);

Return values

The wcstombs function returns the number of bytes converted that make up the converted part of multibyte sequence, not including the terminating null byte. If a wide character was encountered which could not be converted,(size_t)(-1) is returned, and errno set to EILSEQ.

Detailed description

The wcstombs function converts a wide character string wcstring into a multibyte character string, mbstring, beginning in the initial conversion state. Up to nbytes bytes are stored in mbstring. Partial multibyte characters at the end of the string are not stored. The multibyte character string is null terminated if there is room.

The behavior of the wcstombs is affected by LC_CTYPE category of the current locale.

Examples

#include <stdlib.h>
#include <wchar.h>
/* Illustrates how to use wcstombs API */
size_t example_wcstombs(wchar_t *wcs, char *s, size_t n)
{
 size_t len;
 /* converting multibyte string to a wide-char string */
 len = wcstombs(s, (const wchar_t *)wcs, n);
 /* returning no of bytes that make up the multibyte sequence */
 return (len;);
}

Errors

The wcstombs function will fail if:

[`EILSEQ`]
	An invalid wide character was encountered.
[`EINVAL`]
	The conversion state is invalid.

Limitations

The current implementation of wcstombs is not affected by the LC_CTYPE category of the current locale. It works only for UTF8 character set.

Feedback

For additional information or queries on this page send feedback