mbsnrtowcs

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



NAME
       mbsnrtowcs - convert a multibyte string to a wide character 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  incre-
       menting dest by one and *src by the number of bytes consumed. The con-
       version 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 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 proceeds as above,
       except that the converted wide characters are not written out to	 mem-
       ory, and that no destination length limit exists.

       In  both	 of the above cases, if ps is a NULL pointer, a static anony-
       mous 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 characters 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  category  of  the
       current locale.

       Passing NULL as ps is not multi-thread safe.



GNU				  1999-07-25			MBSNRTOWCS(3)