NAME
wctomb —
converts a wide character to a
multibyte character
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 null wide
character (‘\0’), this function places its own internal state
to an initial conversion state.
Calling any other functions in
libc never change
the internal state of
wctomb(),
except for calling
setlocale(3) with the LC_CTYPE category
changed to that of the current locale. Such
setlocale(3) calls cause the internal state of this function to be
indeterminate.
The behaviour of
wctomb()
is affected by LC_CTYPE category of the current
locale.
There is a 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 where the value returned is
greater than the value of the
MB_CUR_MAXmacro. - -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
STANDARDS
The wctomb() function conforms to
ANSI X3.159-1989
(“ANSI C89”).