wcstombs — convert a wide-character string to a multibyte string
#include <stdlib.h>
size_t wcstombs( |
char * | dest, |
const wchar_t * | src, | |
size_t | n) ; |
If dest
is not a
NULL pointer, the wcstombs
()
function converts the wide-character string src
to a multibyte string
starting at dest
. At
most n
bytes are
written to dest
. The
conversion starts in the initial state. The conversion can
stop for three reasons:
A wide character has been encountered that can not be represented as a multibyte sequence (according to the current locale). In this case (size_t)(−1) is returned.
The length limit forces a stop. In this case the
number of bytes written to dest
is returned, but the
shift state at this point is lost.
The wide-character string has been completely
converted, including the terminating L'\0'. In this
case the conversion ends in the initial state. The
number of bytes written to dest
, excluding the
terminating '\0' byte, is returned.
The programmer must ensure that there is room for at least
n
bytes at dest
.
If dest
is NULL,
n
is ignored, and the
conversion proceeds as above, except that the converted bytes
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 wcstombs(NULL,src,0)+1
.
The wcstombs
() function
returns the number of bytes that make up the converted part
of multibyte sequence, not including the terminating null
byte. If a wide character was encountered which could not be
converted, (size_t)(−1) is returned.
The behaviour of wcstombs
()
depends on the LC_CTYPE category of the current locale.
The function wcsrtombs(3) provides a thread safe interface to the same functionality.
|