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





NAME
       mbsrtowcs - convert a multibyte string to a wide charac-
       ter string

SYNOPSIS
       #include <wchar.h>

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

DESCRIPTION
       If dest is not a NULL pointer,  the  mbsrtowcs  function
       converts  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  call-
       ing  mbrtowc(dest,*src,n,ps)  where  n  is some positive
       number, as long as this call succeeds, and  then  incre-
       menting dest by one and *src by the number of bytes con-
       sumed. 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.  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 length
       limit exists.

       In both of the above cases, if ps is a NULL  pointer,  a
       static anonymous state only known to the mbsrtowcs func-
       tion is used instead.

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

RETURN VALUE
       The  mbsrtowcs 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
       ISO/ANSI C, UNIX98

SEE ALSO
       mbstowcs(3), mbsnrtowcs(3), iconv(3)

NOTES
       The behaviour of mbsrtowcs depends on the LC_CTYPE cate-
       gory of the current locale.

       Passing NULL as ps is not multi-thread safe.



GNU                      July 25, 1999             MBSRTOWCS(3)
