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

# bkgrnd(3ncurses)

manipulate background of a curses window of wide characters

## NAME

**bkgrnd**, **wbkgrnd**, **bkgrndset**, **wbkgrndset**, **getbkgrnd**, **wgetbkgrnd** - manipulate background of a *curses* window of wide characters

## SYNOPSIS

```
#include <curses.h>
```

**int bkgrnd(const cchar\_t \****wch***);** **int wbkgrnd(WINDOW \****win***, const cchar\_t \****wch***);**

**void bkgrndset(const cchar\_t \****wch***);** **void wbkgrndset(WINDOW \****win***, const cchar\_t \****wch***);**

**int getbkgrnd(cchar\_t \****wch***);** **int wgetbkgrnd(WINDOW \****win***, cchar\_t \****wch***);**

## DESCRIPTION

**Every** *curses* **window has a** *background character* **property:** **in the library's wide configuration,** **it is a** *curses* **complex character** (*cchar\_t*) **that combines a set of attributes** **(and,** **if colors are enabled,** **a color pair identifier)** **with a character code.** **When erasing** **(parts of)** **a window,** *curses* **replaces the erased cells with the background character.**

*curses* **also uses the background character when writing characters to a** **populated window.**

- •

  **The attribute part of the background character combines with all** **non-blank character cells in the window,** **as populated by the wadd\_wch(3NCURSES) and wins\_wch(3NCURSES)** **families of functions** **(and those that call them).**

- •

  **Both the character code and attributes of the background character** **combine with blank character cells in the window.**

**The background character's set of attributes becomes a property** **of the character cell** **and move with it through any scrolling** **and insert/delete line/character operations.** **To the extent possible on the terminal type,** *curses* **displays the attributes of the background character** **as the graphic rendition of a character cell on the display.**

### bkgrnd, wbkgrnd

**bkgrnd** **and** **wbkgrnd** **set the background property of** **stdscr** **or the specified window and then apply this setting to** **every character cell in that window.**

- •

  **The rendition of every character in the window changes to the new** **background rendition.**

- •

  **Wherever the former background character appears,** **it changes to the new background character.**

*ncurses* **updates the rendition of each character cell by comparing the character,** **non-color attributes,** **and color pair selection.** **The library applies to following procedure to each cell in the window,** **whether or not it is blank.**

- •

  *ncurses* **first compares the cell's character to the previously specified** **background character;** **if they match,** *ncurses* **writes the new background character to the cell.**

- •

  *ncurses* **then checks whether the cell uses color;** **that is,** **its color pair value is nonzero.** **If not,** **it simply replaces the attributes and color pair in the cell with those** **from the new background character.**

- •

  **If the cell uses color,** **and its background color matches that of the current window background,** *ncurses* **removes attributes that may have come from the current background and** **adds those from the new background.** **It finishes by setting the cell's background to use the new window** **background color.**

- •

  **If the cell uses color,** **and its background color does not match that of the current window** **background,** *ncurses* **updates only the non-color attributes,** **first removing those that may have come from the current background,** **and then adding attributes from the new background.**

**If the new background's character is non-spacing,** *ncurses* **reuses the old background character,** **except for one special case:** *ncurses* **treats a background character code of zero (0) as a space.**

**If the terminal does not support color,** **or if color has not been initialized with start\_color(3NCURSES),** *ncurses* **ignores the new background character's color pair selection.**

### bkgrndset, wbkgrndset

**bkgrndset** **and** **wbkgrndset** **manipulate the background of the applicable window,** **without updating the character cells as** **bkgrnd** **and** **wbkgrnd** **do;** **only future writes reflect the updated background.**

### getbkgrnd, wgetbkgrnd

**getbkgrnd** **and** **wgetbkgrnd** **respectively obtain** **stdscr**'s **or the given window's background character,** **attributes,** **and color pair,** **and store it in their** *wch* **argument.**

## RETURN VALUE

**bkgrndset** **and** **wbkgrndset** **do not return a value.**

**Functions returning an** *int* **return** **ERR** **upon failure and** **OK** **upon success.** **In** *ncurses*, **failure occurs if**

- •

  **the** *curses* **screen has not been initialized,**

- •

  *win* **is** *NULL*, **or**

- •

  *wch* **is** *NULL*.

## NOTES

**bkgrnd**, **bkgrndset**, **and** **getbkgrnd** **may be implemented as macros.**

**Unlike their counterparts in the non-wide configuration of** *ncurses*, **getbkgrnd** **and** **wgetbkgrnd** **store the background character in a modifiable** *cchar\_t* **parameter,** **rather than supplying it as the return value.**

## PORTABILITY

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

**X/Open Curses does not provide details of how the rendition is updated.** *ncurses* **follows the approach used in SVr4** *curses*'s **non-wide functions for manipulating the window background.**

## HISTORY

**X/Open Curses Issue 4 (1995) initially specified these functions.**

## SEE ALSO

**bkgd(3NCURSES) describes the corresponding functions in the** **non-wide configuration of** *ncurses*.

**ncurses(3NCURSES),** **add\_wch(3NCURSES),** **attr(3NCURSES)**