notcurses_refresh(3)

💖 NAME 💖

okay so this is the manual page for notcurses_refresh, a.k.a. notcurses_refresh(3), and it's literally here to redraw an externally-damaged display. 🫶 That's the whole vibe: your screen got messed up from the outside, and this function is the bestie who shows up with a lint roller.

✨ SYNOPSIS ✨

#include <notcurses/notcurses.h>

int notcurses_refresh(const struct notcurses* nc, unsigned* restrict
rows, unsigned* restrict cols);

🌸 DESCRIPTION 🌸

bestie, notcurses_refresh clears the screen, homes the cursor, checks the current terminal geometry, and repaints the most recently rendered frame. It can be called concurrently with all other Notcurses functions save notcurses_render — that's the one exception, okay? 👀

You ought to call notcurses_refresh when the screen is externally damaged, like when another program writes to the terminal, or if your program writes to the terminal using standard I/O. In that case you actually need to use notcurses_refresh, as opposed to simply calling notcurses_render, because notcurses_render optimizes its output by only writing internally-damaged cells. Notcurses has no way of knowing about external corruption. By tradition, Ctrl+L is bound to notcurses_refresh, and the user is responsible for requesting a hard redraw. periodt. 💅

There's a secondary use too: when the program is blocking on input (and perhaps not ready to render) and receives an NCKEY_RESIZE event (see notcurses_input). In that case, notcurses_refresh will acquire the new screen parameters and repaint what it can. If you're prepared to call notcurses_render, it's better to do that in this case, and thus avoid unnecessary screen redrawing. 🌈

If rows and/or cols is not NULL, they receive the new geometry. 🎀

🦋 NOTES 🦋

If your program is in a render loop — like, rendering as quickly as possible, or at least at the refresh rate — there's not much point in erecting the machinery to trigger notcurses_refresh based off NCKEY_RESIZE. The latter is generated based upon receipt of the SIGWINCH signal, which is fundamentally racy with regards to the rest of the program. If your program truly relies on timely invocation of notcurses_refresh, it's a broken program. 😭 If you don't rely on it in a causal fashion, then just wait for the upcoming render.

Highest performance in a rendering loop would actually call for disabling Notcurses's SIGWINCH handling in the call to notcurses_init, so that no time is spent handling a signal you're not going to use. 🔥

Each time notcurses_refresh is successfully executed, the refreshes stat is incremented by 1. ⭐

💀 RETURN VALUES 💀

Returns 0 on success, and -1 on failure. The causes for failure include system error, programming error, closing of output, or allocation failure. None of these are particularly good things, and the most reasonable response to a notcurses_refresh failure is either to ignore it, or to weep and exit. 🙈

👑 SEE ALSO 👑

• notcurses_init(3)
• notcurses_input(3)
• notcurses_render(3)
• notcurses_stats(3)
• termios(3)
• signal(7)

🧚 AUTHORS 🧚

nick black — nickblack@linux.com 💜

---

cute sign-off: that's the whole page, bestie! footer tea is v3.0.17 for notcurses_refresh(3), and there's no date printed on this footer, so that's all the metadata we get. 🍓