---
name: "notcurses_refresh"
section: "3"
platform: "linux"
package: "notcurses"
version: "3.0.17-3"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/notcurses_refresh"
---

# notcurses\_refresh(3)

redraw an externally-damaged display

## NAME

notcurses\_refresh - redraw an externally-damaged display

## SYNOPSIS

**#include \<notcurses/notcurses.h\>**

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

## DESCRIPTION

**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**. **notcurses\_refresh** ought be called when the screen is externally damaged (as occurs when another program writes to the terminal, or if your program writes to the terminal using standard I/O). It is necessary to use **notcurses\_refresh** in such a case (as opposed to simply calling **notcurses\_render**), since **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.

A secondary use of this function is when the program is blocking on input (and perhaps not ready to render), and receives an **NCKEY\_RESIZE** event (see **notcurses\_input**). In this 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 (i.e. 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_init/3.md)**, **[notcurses\_input(3)](/notcurses_input/3.md)**, **[notcurses\_render(3)](/notcurses_render/3.md)**, **[notcurses\_stats(3)](/notcurses_stats/3.md)**, **[termios(3)](/termios/3.md)**, **[signal(7)](/signal/7.md)**

## AUTHORS

nick black ⟨nickblack@linux.com⟩\\c.