getcchar(3NCURSES)

✨ getcchar(3NCURSES) — the bestie guide 💖

okay so we're in the ncurses library-calls section, and today's main characters are getcchar and setcchar, aka the little translators that go back and forth between a wide-character string and a curses complex character. no cap. 🦋

---

🌸 NAME 🌸

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

---

🎀 SYNOPSIS 🎀

#include <curses.h>

int gettchar(const cchar_t * wch, wchar_t * wc,
      attr_t * attrs, short * pair, void * opts);
int settchar(cchar_t * wch, const wchar_t * wc,
      const attr_t attrs, short pair, const void * opts);

and yes, that spelling is exactly what the page says, bestie — i'm not touching a single character of it. 🤐

---

💖 DESCRIPTION 💖

So the curses complex character data type cchar_t is a struct type that's basically a lil trio: a wide-character string, a set of attributes, and a color pair identifier. the way that cchar_t is opaque though — do not go poking at its members directly, that's not the vibe. 🙈 the library hands you functions to manipulate this type instead, and that's what we're here for.

🫶 getcchar

getcchar destructures a cchar_t into its components. it's giving "unpack the fit". 💅

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. so it's just doing a lil headcount and dipping. 🔥

⭐ setcchar

setcchar constructs a curses complex character wch from the components wc, attrs, and pair. main character energy: it's building the thing. 👑

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. periodt.

up to CCHARW_MAX - 1 non-spacing characters may follow (see curses_variables(3NCURSES)). ncurses ignores any additional non-spacing characters — it's just not gonna deal with them. 💀

the string may contain a single control character instead. in that case, no non-spacing characters are allowed. that's the rule, fr fr.

---

🌈 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. so like… don't. 🫶

---

👑 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. iconic behavior honestly.

• 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. iykyk.

these functions are described in X/Open Curses Issue 4. it specifies no error conditions for them. wild.

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. a lil history lesson, bestie: 📜

• 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. 💀 not the overlooked detail era.

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. so, like, careful. 🚨

---

💜 HISTORY 💜

X/Open Curses Issue 4 (1995) initially specified these functions. the origin story. 🎬

---

🌟 SEE ALSO 🌟

ncurses(3NCURSES), attr(3NCURSES), color(3NCURSES), wcwidth(3)

---

and that's the whole page, bestie!! 🎀 this was ncurses 6.5, dated 2025-02-01 — mwah, slay, go forth and never touch a cchar_t member directly. 💖✨🌸