WCTOMB(3) | Library Functions Manual | WCTOMB(3)

# NAME

`wctomb` — converts a wide character to a multibyte character

# SYNOPSIS

`#include <stdlib.h>`

int
`wctomb`(char * s, wchar_t wchar);

# DESCRIPTION

The `wctomb`() function 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_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”).

March 29, 2022 | Debian