---
name: "clear"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/clear/3"
---

# clear(3)

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(3X)) merged into them.**

### clear, wclear

**The clear and wclear routines are like erase and** **werase, but they also call clearok(3X), 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

**curses(3X),** **curs\_outopts(3X),** **curs\_refresh(3X),** **curs\_variables(3X)**