wcsrtombs - convert a wide character string to a multibyte
string
SYNOPSIS
#include <wchar.h>
size_t wcsrtombs (char *dest, const wchar_t **src,
size_t len, mbstate_t *ps);
DESCRIPTION
If dest is not a NULL pointer, the wcsrtombs function con
verts the wide-character string *src to a multibyte string
starting at dest. At most len bytes are written to dest.
The shift state *ps is updated. The conversion is effec
tively performed by repeatedly calling wcr
tomb(dest,*src,ps), as long as this call succeeds, and
then incrementing dest by the number of bytes written and
*src by one. The conversion can stop for three reasons:
1. A wide character has been encountered that can not be
represented as a multibyte sequence (according to the cur
rent locale). In this case *src is left pointing to the
invalid wide character, (size_t)(-1) is returned, and
errno is set to EILSEQ.
2. The length limit forces a stop. In this case *src is
left pointing to the next wide character to be converted,
and the number of bytes written to dest is returned.
3. The wide-character string has been completely con
verted, including the terminating L'\0' (which has the
side effect of bringing back *ps to the initial state). In
this case *src is set to NULL, and the number of bytes
written to dest, excluding the terminating '\0' byte, is
returned.
If dest is NULL, len is ignored, and the conversion pro
ceeds as above, except that the converted bytes are not
written out to memory, and that no length limit exists.
In both of the above cases, if ps is a NULL pointer, a
static anonymous state only known to the wcsrtombs func
tion is used instead.
The programmer must ensure that there is room for at least
len bytes at dest.
RETURN VALUE
The wcsrtombs function returns the number of bytes 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.
ISO/ANSI C, UNIX98
SEE ALSO
wcstombs(3), wcsnrtombs(3), iconv(3)
NOTES
The behaviour of wcsrtombs depends on the LC_CTYPE cate
gory of the current locale.
Passing NULL as ps is not multi-thread safe.
Man(1) output converted with
man2html