wcrtomb

Name

wcrtomb - convert a wide character to a multibyte sequence

Library

libc.lib

Synopsis

#include <wchar.h>

size_t wcrtomb (char * restrict dst, wchar_t src, mbstate_t * restrict ps);
Sh RETURN VALUES The wcrtomb functions returns the length (in bytes) of the multibyte sequence needed to represent wc, or (size_t-1) if wc is not a valid wide character code.

Detailed description

The wcrtomb function stores a multibyte sequence representing the wide character wc, including any necessary shift sequences, to the character array s, storing a maximum of MB_CUR_MAX bytes.

If s is NULL, wcrtomb behaves as if s pointed to an internal buffer and wc was a null wide character (L’\0’).

The

mbstate_t argument, ps, is used to keep track of the shift state. If it is NULL, wcrtomb uses an internal, static mbstate_t object, which is initialized to the initial conversion state at program startup.

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

Examples

#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
/* Illustrates how to use wcrtomb API */
int example_wcrtomb(wchar_t wc)
{
  char s[MAX_CUR_MAX];
  size_t len;
  mbstate_t mbs;
  
  /* represent a wide-char in a single byte*/
  len = wcrtomb(s, wc, &mbs);
  /* return the number of bytes */
  return(len);
}

Errors

The wcrtomb function will fail if:

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

Limitations

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