mbstowcs

Name

mbstowcs - converts a multibyte string to a wide character string

Library

libc.lib

Synopsis

#include <stdlib.h>

size_t mbstowcs (wchar_t * restrict dst, const char * restrict src, size_t nwchars);

Return values

The mbstowcs function returns the number of wide characters converted, not counting any terminating null wide character, or -1 if an invalid multibyte character was encountered.

Detailed description

The mbstowcs function converts a multibyte character string mbstring beginning in the initial conversion state into a wide character string wcstring. No more than nwchars wide characters are stored. A terminating null wide character is appended if there is room.

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

Examples

#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
/* Illustrates how to use mbstowcs API */
size_t example_mbstowcs(wchar_t *wc, char *s, size_t n)
{
 size_t len;
 /* converting multibyte string to a wide-char string */
 len = mbstowcs(wc, s, n);
 /* checking for error */
 if(len < 0)
 {
        wprintf(L"mbstowcs returned error!!\n");
 }
 /* returning no of bytes consumed */
 return (len);
}

Errors

The mbstowcs function will fail if:

[`EILSEQ`]
	An invalid multibyte sequence was detected.
[`EINVAL`]
	The conversion state is invalid.

Limitations

The current implementation of mbstowcs 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