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 8.0