MBSNRTOWCS(3)      Linux Programmer's Manual      MBSNRTOWCS(3)





NAME
       mbsnrtowcs  - convert a multibyte string to a wide char-
       acter 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, start-
       ing 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 per-
       formed  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 multi-
       byte  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
       converted,  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' character, is returned.

       If dest is NULL, len is ignored, and the conversion pro-
       ceeds as above, except that the converted  wide  charac-
       ters are not written out to memory, and that no destina-
       tion length limit exists.

       In both of the above cases, if ps is a NULL  pointer,  a
       static  anonymous  state  only  known  to the mbsnrtowcs
       function is used instead.

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

RETURN VALUE
       The mbsnrtowcs function returns the number of wide char-
       acters that make up the converted part of the wide char-
       acter  string,  not  including the terminating null wide
       character. If an invalid multibyte sequence was  encoun-
       tered,  (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 cat-
       egory of the current locale.

       Passing NULL as ps is not multi-thread safe.



GNU                      July 25, 1999            MBSNRTOWCS(3)
