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





NAME
       mbstowcs  - convert a multibyte string to a wide charac-
       ter 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
       converts  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 termi-
       nating 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  pro-
       ceeds  as  above, except that the converted wide charac-
       ters 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 charac-
       ter  string,  not  including  the  terminating null wide
       character. If an invalid multibyte sequence was  encoun-
       tered, (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 cate-
       gory of the current locale.

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



GNU                      July 25, 1999              MBSTOWCS(3)
