NAME
wctomb —
converts a wide character to a
multibyte character
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdlib.h>
int
wctomb(
char *
s,
wchar_t wchar);
DESCRIPTION
The
wctomb() converts the wide character
wchar to the corresponding multibyte character, and
stores it in the array pointed to by
s.
wctomb() may store at most
MB_CUR_MAX
bytes in the array.
In state-dependent encoding,
wctomb() may store the special
sequence to change the conversion state before an actual multibyte character
into the array pointed to by
s. If
wchar is a nul wide character (‘\0’), this
function sets its own internal state to an initial conversion state.
Calling any other functions in
Standard C Library (libc,
-lc) never changes the internal state of
wctomb(),
except changing the
LC_CTYPE
category of the current
locale by calling
setlocale(3). Such
setlocale(3) calls cause the
internal state of this function to be indeterminate.
The behaviour of
wctomb() is affected by the
LC_CTYPE
category of the current locale.
There is one special case:
-
-
- s == NULL
- wctomb() initializes its own internal
state to an initial state, and determines whether the current encoding is
state-dependent. This function returns 0 if the encoding is
state-independent, otherwise non-zero. In this case,
wchar is completely ignored.
RETURN VALUES
Normally,
wctomb() returns:
-
-
- positive
- Number of bytes for the valid multibyte character pointed
to by s. There are no cases that the value returned
is greater than n or the value of the
MB_CUR_MAX
macro.
-
-
- -1
- wchar is an invalid wide
character.
If
s is equal to
NULL
,
wctomb() returns:
-
-
- 0
- The current encoding is state-independent.
-
-
- non-zero
- The current encoding is state-dependent.
ERRORS
No errors are defined.
SEE ALSO
setlocale(3)
STANDARDS
The
wctomb() function conforms to
ANSI
X3.159-1989 (“ANSI C89”).