mbstowcs  - convert a multibyte string to a wide character
       string


SYNOPSIS

       #include <stdlib.h>

       size_t mbstowcs (wchar_t *dest, const char *src, size_t n);


DESCRIPTION

       If dest is not a NULL pointer, the mbstowcs function  con­
       verts  the multibyte string src to a wide-character string
       starting at dest.  At most n wide characters  are  written
       to  dest.  The conversion starts in the initial state. The
       conversion can stop for three reasons:

       1. An invalid multibyte sequence has been encountered.  In
       this case (size_t)(-1) is returned.

       2.  n  non-L'\0' wide characters have been stored at dest.
       In this case the number of wide characters written to dest
       is returned, but the shift state at this point is lost.

       3.  The  multibyte  string  has been completely converted,
       including the terminating '\0'. In this case the number of
       wide characters written to dest, excluding the terminating
       L'\0' character, is returned.

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

       If dest is NULL, n is ignored, and the conversion proceeds
       as above, except that the converted  wide  characters  are
       not  written  out  to  memory,  and  that  no length limit
       exists.

       In order to avoid the case 2 above, the programmer  should
       make sure n is greater or equal to mbstowcs(NULL,src,0)+1.


RETURN VALUE

       The mbstowcs 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.


CONFORMING TO

       ISO/ANSI C, UNIX98


SEE ALSO

       mbsrtowcs(3)


NOTES

       The behaviour of mbstowcs depends on the LC_CTYPE category


       The  function mbsrtowcs provides a better interface to the
       same functionality.


Man(1) output converted with man2html