curs_clear(3X)

💖 curs_clear — the "clear all or part of a curses window" page, bestie edition 💖

okay so this is curs_clear(3X) from the ncurses library-calls girlies, and it's literally all about wiping your window clean. no cap. 🧼✨

---

🌸 NAME 🌸

erase, werase, clear, wclear, clrtobot, wclrtobot, clrtoeol, wclrtoeol — clear all or part of a curses window 🫧

---

✨ SYNOPSIS ✨

#include <curses.h>

int erase(void);
int werase(WINDOW *win);

int clear(void);
int wclear(WINDOW *win);

int clrtobot(void);
int wclrtobot(WINDOW *win);

int clrtoeol(void);
int wclrtoeol(WINDOW *win);

---

💅 DESCRIPTION 💅

🎀 erase, werase

erase and werase copy blanks into every single position in the window. like, the whole thing. cleared. screen empty. iconic. 🌈

and bestie, the blanks that erasure makes? they get the current background rendition merged into them — that's the one set by wbkgdset(3X). so they're not just "blank", they're styled blank. 💅

🎀 clear, wclear

clear and wclear are giving the same energy as erase and werase, BUT — and this is the plot twist 🫢 — they also call clearok(3X). what that means: the screen gets cleared completely on the next wrefresh for that window, and it's repainted from scratch. full reset. main character energy. 👑

🎀 clrtobot, wclrtobot

clrtobot and wclrtobot erase from the cursor all the way to the end of screen. so basically: every line below the cursor in the window, gone. and also the current line, from the cursor rightward <em>inclusive</em>, is erased too. yes inclusive. we don't do half measures. 💀

🎀 clrtoeol, wclrtoeol

clrtoeol and wclrtoeol erase the current line, from the cursor rightward <em>inclusive</em>, to the end of the current line. just that one line, bestie. precision. 🎯

---

🦋 RETURN VALUE 🦋

every one of these routines returns the integer OK when it slays, and ERR when it doesn't. 😭

in this implementation specifically:

• functions that take a window pointer parameter return ERR if that pointer is null 🚫
• wclrtoeol returns an error if the cursor position is about to wrap 😳

---

⭐ NOTES ⭐

erase, werase, clear, wclear, clrtobot, and clrtoeol may be implemented as macros. so like, don't be weird about it. 🙈

---

🌈 PORTABILITY 🌈

X/Open Curses Issue 4 describes these functions. it specifies no error conditions for them. none. zero. ngl. 💀

SVr4 documentation says these functions return OK <em>"or a non-negative integer if immedok() is set"</em> — and that's referring to the return value from wrefresh, which in SVr4 returns a count of characters written to the window if its immedok property is set. in ncurses? it does not. fr fr. 🚫

some historic curses implementations had, as an <em>undocumented feature</em>, the ability to do the equivalent of clearok(..., 1) by saying touchwin(stdscr) or clear(stdscr). > heads up bestie: this will not work under ncurses. not even a little. 😤

this implementation, and others such as Solaris, sets the current position to 0,0 after erasing via werase and wclear. that fact is not documented in other implementations, and may not be true of implementations which weren't derived from SVr4 source. so don't count on it everywhere. 👀

and not obvious from the description: most implementations clear the screen after wclear even for a subwindow or derived window. so if you do <em>not</em> want the screen cleared during the next wrefresh, use werase instead. that's the whole tea. 🍵

---

👑 SEE ALSO 👑

curses(3X), curs_outopts(3X), curs_refresh(3X), curs_variables(3X)

---

and that's the page, bestie!! 🫶 this one's from ncurses 6.6, dated 2025-01-18, and it's the curs_clear(3X) manual page — go clear a window and serve absolute looks. mwah. 💖✨🎀🦋🌸