wcsnrtombs - convert a wide character string to a multi
byte string
SYNOPSIS
#include <wchar.h>
size_t wcsnrtombs (char *dest, const wchar_t **src, size_t nwc,
size_t len, mbstate_t *ps);
DESCRIPTION
The wcsnrtombs function is like the wcsrtombs function,
except that the number of wide characters to be converted,
starting at *src, is limited to nwc.
If dest is not a NULL pointer, the wcsnrtombs function
converts at most nwc wide characters from the wide-charac
ter 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 effectively performed by
repeatedly calling wcrtomb(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. nwc wide characters have been converted without encoun
tering a L'\0', or 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 destination length
limit exists.
In both of the above cases, if ps is a NULL pointer, a
static anonymous state only known to the wcsnrtombs func
tion is used instead.
The programmer must ensure that there is room for at least
RETURN VALUE
The wcsnrtombs 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.
CONFORMING TO
This function is a GNU extension.
SEE ALSO
wcsrtombs(3), iconv(3)
NOTES
The behaviour of wcsnrtombs 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