size_t
mbstowcs(
wchar_t * restrict pwcs
, const char * restrict s
, size_t n
)
)
converts a nul-terminated multibyte character string pointed to by
s
to the corresponding wide character string and stores it in the array
pointed to by
pwcs
.
This function may modify the first at most
n
elements of the array pointed to by
pwcs
.
Each character will be converted as if
mbtowc(3)
is continuously called, except the internal state of
mbtowc(3)
will not be affected.
For state-dependent encoding,
mbstowcs()
implies the multibyte character string pointed to by
s
always begins with an initial state.
These are the special cases:
)
returns the number of elements to store the whole wide character string
corresponding to the multibyte character string pointed to by
s
.
In this case,
n
is ignored.
)
returns:
pwcs
.
There are no cases that the value returned is greater than
n
(unless
pwcs
is a null pointer) or the value of the
MB_CUR_MAX
macro.
If the return value is equal to
n
,
the string pointed to by
pwcs
will not be nul-terminated.
s
points to a string containing an invalid or incomplete multibyte character.
The
mbstowcs(
)
also sets
errno
to indicate the error.
)
may cause an error in the following case:
EILSEQ
]
s
points to a string containing an invalid or incomplete multibyte character.
)
function conforms to
ANSI X3.159-1989 (``ANSI C89'') .
The restrict qualifier is added at
ISO/IEC 9899:1999 (``ISO C99'') .