WCTOMB(3)

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

# 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”).

February 3, 2002 | NetBSD 10.1