mbsnrtowcs  - convert a multibyte string to a wide charac­
       ter string


SYNOPSIS

       #include <wchar.h>

       size_t mbsnrtowcs (wchar_t *dest, const char **src,
                          size_t nms, size_t len, mbstate_t *ps);


DESCRIPTION

       The mbsnrtowcs function is like  the  mbsrtowcs  function,
       except  that the number of bytes to be converted, starting
       at *src, is limited to nms.

       If dest is not a NULL  pointer,  the  mbsnrtowcs  function
       converts  at most nms bytes from the multibyte string *src
       to a wide-character string starting at dest.  At most  len
       wide  characters  are written to dest. The shift state *ps
       is updated. The conversion  is  effectively  performed  by
       repeatedly calling mbrtowc(dest,*src,n,ps) where n is some
       positive number, as long as this call succeeds,  and  then
       incrementing  dest  by one and *src by the number of bytes
       consumed. The conversion can stop for three reasons:

       1. An invalid multibyte sequence has been encountered.  In
       this  case  *src is left pointing to the invalid multibyte
       sequence, (size_t)(-1) is returned, and errno  is  set  to
       EILSEQ.

       2.  The  nms  limit  forces  a stop, or len non-L'\0' wide
       characters have been stored at dest. In this case *src  is
       left  pointing  to  the next multibyte sequence to be con­
       verted, and the number of wide characters written to  dest
       is returned.

       3.  The  multibyte  string  has been completely converted,
       including the terminating '\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  wide  characters
       written  to  dest, excluding the terminating L'\0' charac­
       ter, is returned.

       If dest is NULL, len is ignored, and the  conversion  pro­
       ceeds  as above, except that the converted wide characters
       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 mbsnrtowcs  func­
       tion is used instead.

       The programmer must ensure that there is room for at least
       len wide characters at dest.

       The mbsnrtowcs function returns the number of wide charac­
       ters that make up the converted part of the wide character
       string, not including the terminating null wide character.
       If   an   invalid   multibyte  sequence  was  encountered,
       (size_t)(-1) is returned, and errno set to EILSEQ.


CONFORMING TO

       This function is a GNU extension.


SEE ALSO

       mbsrtowcs(3), iconv(3)


NOTES

       The behaviour of mbsnrtowcs 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