# curs_bkgd 3x 2025-08-23 ncurses 6.5 Library calls

    curs_bkgd(3x)                    Library calls                   curs_bkgd(3x)

## NAME

           bkgdset,  wbkgdset,  bkgd,  wbkgd, getbkgd - manipulate background of a
           curses window of characters

## SYNOPSIS

           #include <curses.h>

           int bkgd(chtype ch);
           int wbkgd(WINDOW *win, chtype ch);

           void bkgdset(chtype ch);
           void wbkgdset(WINDOW *win, chtype ch);

           chtype getbkgd(WINDOW *win);

## DESCRIPTION

           Every curses  window  has  a  background  character  property:  in  the
           library's  non-wide-character  configuration,  it is a curses character
           (chtype) 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.

           o   The attribute part of the background character  combines  with  all
               non-blank  character  cells  in  the  window,  as  populated by the
               waddch(3x) and winsch(3x) families of  functions  (and  those  that
               call them).

           o   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.

### bkgd, wbkgd

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

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

           o   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 the following procedure to each cell in the window, whether  or
           not it is blank.

           o   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.

           o   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.

           o   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.

           o   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 (for example, if it is
           a   control   character),   ncurses  retains  the  existing  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(3x), ncurses ignores  the  new  background
           character's color pair selection.

### bkgdset, wbkgdset

           bkgdset  and  wbkgdset  manipulate  the  background  of  the applicable
           window, without updating the character cells as bkgd and wbkgd do; only
           future writes reflect the updated background.

### getbkgd

           getbkgd  returns  the  given window's background character, attributes,
           and color pair as a chtype.

## RETURN VALUE

           bkgdset and wbkgdset do not return a value.

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

           o   the curses screen has not been initialized, or

           o   win is NULL.

           getbkgd's return value is as described above.

## NOTES

           Unusually,  there is no wgetbkgd function; getbkgd behaves as one would
           expect wgetbkgd to, accepting a WINDOW pointer argument.

           bkgd and bkgdset may be implemented as macros.

           X/Open Curses mentions that the character part of the  background  must
           be  a  single-byte  value.  ncurses, like SVr4 curses, checks to ensure
           that it is, and retains the existing background character if the  check
           fails.

## PORTABILITY

           X/Open  Curses  Issue 4  describes  these functions.  It indicates that
           bkgd, wbkgd, and getbkgd return ERR on failure  (in  the  case  of  the
           last,  this value is cast to chtype), but specifies no error conditions
           for them.

           SVr4 documentation says that bkgd  and  wbkgd  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.

           Neither  X/Open  Curses  nor  the  SVr4  manual  pages  detail  how the
           rendition of characters in  the  window  updates  when  bkgd  or  wbkgd
           changes  the background character.  ncurses, like SVr4 curses, does not
           (in its non-wide-character  configuration)  store  the  background  and
           window attribute contributions to each character cell separately.

## HISTORY

           SVr3.1 (1987) introduced these functions.

## SEE ALSO

           curs_bkgrnd(3x)  describes  the  corresponding  functions  in  the wide
           configuration of ncurses.

           curses(3x), curs_addch(3x), curs_attr(3x)

    ncurses 6.5                       2025-08-23                     curs_bkgd(3x)