---
name: "getcchar"
section: "3x"
platform: "linux"
package: "ncurses"
version: "6.6-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/curs_getcchar/3x"
---

# getcchar(3x)

convert between a wide-character string and a curses complex character

Part of [curs\_getcchar(3x)](/curs_getcchar/3x.md).

## NAME

**getcchar**, **setcchar** - convert between a wide-character string and a *curses* complex character

## SYNOPSIS

```
#include <curses.h>
```

**int getcchar(const cchar\_t \*** *wch***, wchar\_t \*** *wc***,**\
       **attr\_t \*** *attrs***, short \*** *pair***, void \*** *opts***);** **int setcchar(cchar\_t \*** *wch***, const wchar\_t \*** *wc***,**\
       **const attr\_t** *attrs***, short** *pair***, const void \*** *opts***);**

## DESCRIPTION

**The** *curses* **complex character data type** *cchar\_t* **is a structure type comprising** **a wide-character string,** **a set of attributes,** **and** **a color pair identifier.** **The** *cchar\_t* **structure is opaque;** **do not attempt to access its members directly.** **The library provides functions to manipulate this type.**

### getcchar

**getcchar** **destructures a** *cchar\_t* **into its components.**

**If** *wc* **is not a null pointer,** **getcchar**:

- •

  **stores the wide-character string in the** *curses* **complex character** *wch* **into** *wc*;

- •

  **stores the attributes in** *attrs*; **and**

- •

  **stores the color pair identifier in** *pair*.

**If** *wc* **is a null pointer,** **getcchar** **counts the** *wchar\_t* **wide characters in** *wch*, **returns that value,** **and leaves** *attrs* **and** *pair* **unchanged.**

### setcchar

**setcchar** **constructs a** *curses* **complex character** *wch* **from the components** *wc*, *attrs*, **and** *pair*. **The wide-character string** *wch* **must be terminated with a null wide character** **L'\\0'** **and must contain at most one spacing character,** **which,** **if present,** **must be the first wide character in the string.**

**Up to** **CCHARW\_MAX** - 1 **non-spacing characters may follow** **(see curs\_variables(3X)).** *ncurses* **ignores any additional non-spacing characters.**

**The string may contain a single control character instead.** **In that case,** **no non-spacing characters are allowed.**

## RETURN VALUE

**If** **getcchar** **is passed a null pointer as its** *wc* **argument,** **it returns the number of wide characters for a given** *wch* **that it would store in** *wc*, **counting a trailing null wide character.** **If** **getcchar** **is not passed a null pointer as its** *wc* **argument,** **it returns** **OK** **on success and** **ERR** **on failure.**

**In** *ncurses*, **getcchar** **returns** **ERR** **if either** *attrs* **or** *pair* **is a null pointer and** *wc* **is not.**

**setcchar** **returns** **OK** **on success and** **ERR** **on failure.**

**In** *ncurses*, **setcchar** **returns** **ERR** **if**

- •

  *wch* **is a null pointer,**

- •

  *wc* **starts with a (wide) control character** **and contains any other wide characters,** **or**

- •

  *pair* **has a negative value.**

## NOTES

*wch* **may be a value stored by** **setcchar** **or another** *curses* **function with a writable** *cchar\_t* **argument.** **If** *wch* **is constructed by any other means,** **the library's behavior is unspecified.**

## EXTENSIONS

**X/Open Curses documents the** *opts* **argument as reserved for future use,** **saying that it must be a null pointer.** **The** *ncurses* 6 **ABI uses it with functions that have a color pair parameter** **to support extended color pairs.**

- •

  **In functions that assign colors,** **such as** **setcchar**, **if** *opts* **is not a null pointer,** *ncurses* **treats it as a pointer to** *int*, **and interprets it instead of the** *short* *pair* **parameter as a color pair identifier.**

- •

  **In functions that retrieve colors,** **such as** **getcchar**, **if** *opts* **is not a null pointer,** *ncurses* **treats it as a pointer to** *int*, **and stores the retrieved color pair identifier there** **as well as in the** *short* *pair* **parameter** **(which may therefore undergo a narrowing conversion).**

## PORTABILITY

**Applications employing** *ncurses* **extensions should condition their use on the visibility of the** **NCURSES\_VERSION** **preprocessor macro.**

**These functions are described in X/Open Curses Issue 4.** **It specifies no error conditions for them.**

**X/Open Curses does not detail the layout of the** *cchar\_t* **structure,** **describing only its minimal required contents:**

- •

  **a spacing wide character** (*wchar\_t*),

- •

  **at least five non-spacing wide characters** (*wchar\_t*; **see below),**

- •

  **attributes** **(at least 15 bits' worth,** **inferred from the count of specified** *WA\_* **constants),**

- •

  **a color pair identifier** **(at least 16 bits,** **inferred from the** *short* **type used to encode it).**

**Non-spacing characters are optional,** **in the sense that zero or more may be stored in a** *cchar\_t*. **XOpen/Curses specifies a limit:**

**Implementations may limit the number of non-spacing characters that can** **be associated with a spacing character,** **provided any limit is at least 5.**

**Then-contemporary Unix implementations adhered to that limit.**

- •

  **AIX 4 and OSF/1 4 used the same declaration with** **a single spacing wide character** *c* **and an array of 5 non-spacing wide characters** *z*.

- •

  **HP-UX 10 used an opaque structure of 28 bytes,** **large enough for 6** *wchar\_t* **values.**

- •

  **Solaris** *xcurses* **uses a single array of 6** *wchar\_t* **values.**

*ncurses* **defined its** *cchar\_t* **in 1995 using 5 as the** *total* **of spacing and non-spacing characters** (**CCHARW\_MAX**). **That was probably due to a misreading of the AIX 4 header files,** **because the X/Open Curses document** **was not generally available at that time.** **Later (in 2002),** **this detail was overlooked when work began to implement the functions** **using the structure.**

**In practice,** **a mere four non-spacing characters may seem adequate.** **X/Open Curses documents possible applications of non-spacing characters,** **including their use as ligatures** **(a feature apparently not supported by any** *curses* **implementation).** **Unicode does not limit the (analogous) number of combining characters** **in a grapheme cluster;** **some applications may be affected.** *ncurses* **can be compiled with a different** **CCHARW\_MAX** **value;** **doing so alters the library's ABI.**

## HISTORY

**X/Open Curses Issue 4 (1995) initially specified these functions.**

## SEE ALSO

**curses(3X),** **curs\_attr(3X),** **curs\_color(3X),** **[wcwidth(3)](/wcwidth/3.md)**