MBSTOWCS(3) BSD Library Functions Manual MBSTOWCS(3)NAME
mbstowcs — converts a multibyte character string to a wide-character
string
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdlib.h>
size_t
mbstowcs(wchar_t * restrict pwcs, const char * restrict s, size_t n);
DESCRIPTIONmbstowcs() 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 con‐
verted 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:
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
ignored.
s == NULL Undefined (may cause 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 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.
(size_t)-1 s points to a string containing an invalid or incomplete
multibyte character. The mbstowcs() also sets errno to
indicate the error.
ERRORSmbstowcs() may cause an error in the following case:
[EILSEQ] s points to a string containing an invalid or incom‐
plete multibyte character.
SEE ALSOmbtowc(3), setlocale(3), wcstombs(3)STANDARDS
The mbstowcs() function conforms to ANSI X3.159-1989 (“ANSI C89”). The
restrict qualifier is added at ISO/IEC 9899:1999 (“ISO C99”).
BSD March 16, 2011 BSD