mbstowcs(3)
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 theterminating '\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 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.25 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/.