CURSES_CCHAR(3)

CURSES_CCHAR(3) | Library Functions Manual | CURSES_CCHAR(3)

# NAME

`curses_cchar`, `getcchar`, `setcchar` —
curses representation of wide characters

# LIBRARY

Curses Library (libcurses, -lcurses)

# SYNOPSIS

`#include <curses.h>`

int
`getcchar`(const cchar_t *wcval, wchar_t *wch, attr_t *attrs, short *color_pair, void *opts);

int
`setcchar`(cchar_t *wcval, const wchar_t *wch, const attr_t attrs, short color_pair, const void *opts);

# DESCRIPTION

Curses uses the opaque type cchar_t to represent a string of wide characters up to an implementation-dependent length along with a color pair and zero or more attributes. A null cchar_t object is an object that references an empty wide-character string. Arrays of cchar_t objects are terminated by a null cchar_t object.

Objects of type cchar_t can be manipulated using the `getcchar` and `setcchar` functions. Both these functions take as their last parameter the opts argument which is reserved for future extensions. Currently, the application must provide a null pointer as opts.

When the `getcchar` function is called with non-null wch it extracts the information from the wcval object. The string of wide characters in wcval is copied to the wch array. The attributes are stored in attrs and the color pair is stored in color_pair. In this case it returns `OK` upon successful completion, and `ERR` otherwise.

When `getcchar` is called with null wch it doesn't store any information but returns the number of wide characters referenced by wcval, including the null terminator.

`setcchar` initializes wcval with the wide-character string wch, attributes attrs, and color pair color_pair.

# RETURN VALUES

`getchar` called with null wch returns the number of wide characters referenced by wcval, including the null terminator.

Otherwise these functions return one of the following values:

`OK`
  The function completed successfully.
`ERR`
  An error occurred in the function.

# STANDARDS

The NetBSD Curses library complies with the X/Open Curses specification, part of the Single Unix Specification.

# HISTORY

The Curses package appeared in 4.0BSD.

Wide characters support appeared in NetBSD 5.0.

November 19, 2018 | NetBSD 10.0