MBSTOWCS(3) BSD Programmer's Manual MBSTOWCS(3)NAMEmbstowcs - converts a multibyte character string to a wide character
SYNOPSIS
#include <stdlib.h>
size_t
mbstowcs(wchar_t * restrict pwcs, const char * restrict s, size_t n);
DESCRIPTION
The mbstowcs() converts a null-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 begin with an initial state.
These are the special cases:
pwcs == NULL mbstowcs() 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 ig-
nored.
s == NULL Undefined (may causes the program to crash).
RETURN VALUESmbstowcs() returns:
0 or positive
Number of elements stored in the array pointed to by pwcs.
There are no cases where 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 null-terminated.
(size_t)-1 s points to the string containing invalid or incomplete
multibyte character. The mbstowcs() also sets errno to in-
dicate the error.
ERRORSmbstowcs() may cause an error in the following cases:
[EILSEQ] s points to the string containing invalid or incomplete
multibyte character.
SEE ALSOmbtowc(3), setlocale(3)STANDARDS
The mbstowcs() function conforms to ANSI X3.159-1989 ("ANSI C"). The res-
trict qualifier is added at ISO/IEC 9899/199 ("ISO C99").
MirOS BSD #10-current February 3, 2002 1
