---
name: "clear"
section: "3ncurses"
platform: "linux"
package: "ncurses-doc"
version: "6.5+20250216-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/clear/3ncurses"
---

# clear(3ncurses)

clear all or part of a curses window

## 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

**The erase and werase routines copy blanks to every** **position in the window, clearing the screen.**

**Blanks created by erasure have the current background rendition (as set** **by wbkgdset(3NCURSES)) merged into them.**

### clear, wclear

**The clear and wclear routines are like erase and** **werase, but they also call clearok(3NCURSES), so that the screen is** **cleared completely on the next call to wrefresh for that window** **and repainted from scratch.**

### clrtobot, wclrtobot

**The clrtobot and wclrtobot routines erase from the cursor to the** **end of screen.** **That is, they erase all lines below the cursor in the window.** **Also, the current line to the right of the cursor, inclusive, is erased.**

### clrtoeol, wclrtoeol

**The clrtoeol and wclrtoeol routines erase the current line** **to the right of the cursor, inclusive, to the end of the current line.**

## RETURN VALUE

**All routines return the integer OK on success and ERR on failure.**

**In this implementation,**

- •

  **functions using a window pointer parameter return** **ERR** **if it 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.**

## PORTABILITY

**X/Open Curses Issue 4 describes these functions.** **It specifies no error conditions for them.**

**SVr4 documentation** **says that these functions return** *OK* **“or a non-negative integer if** *immedok()* **is set”,** **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.**

**Some historic curses implementations had, as an undocumented feature, the** **ability to do the equivalent of clearok(..., 1) by saying** **touchwin(stdscr) or clear(stdscr).** **This will not work under** *ncurses***.**

**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 were not derived from SVr4 source.**

**Not obvious from the description,** **most implementations clear the screen after wclear** **even for a subwindow or derived window.** **If you do not want to clear the screen during the next wrefresh,** **use werase instead.**

## SEE ALSO

**ncurses(3NCURSES),** **outopts(3NCURSES),** **refresh(3NCURSES),** **curses\_variables(3NCURSES)**