NAME
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 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 terminating L'\0' character, is returned. |
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 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.
CONFORMING TO
C99.
NOTES
The behavior of mbstowcs() depends on the LC_CTYPE category of the current locale.
The function mbsrtowcs(3) provides a better interface to the same functionality.
SEE ALSO
COLOPHON
This page is part of release 3.23 of the Linux man-pages project. A description of the project, and information about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.
