# curs_scroll 3x 2025-04-05 ncurses 6.5 Library calls

    curs_scroll(3x)                  Library calls                 curs_scroll(3x)

## NAME

           scroll, scrl, wscrl - scroll a curses window

## SYNOPSIS

           #include <curses.h>

           int scroll(WINDOW * win);

           int scrl(int n);
           int wscrl(WINDOW * win, int n);

## DESCRIPTION

           scroll  scrolls  the  given window up one line.  That is, every visible
           line we might number i becomes line i-1.  wscrl  and  scrl  scroll  the
           specified window or stdscr, respectively, up or down per the sign of n.

           o   For positive n, line i+n becomes i (scrolling up);

           o   for negative n, line i-n becomes i (scrolling down).

           A  line  that  scrolls  beyond the window boundaries disappears; curses
           populates a  new  one  emerging  at  the  opposite  boundary  with  the
           background   character;   see   bkgd(3x)   (wide-character  API  users:
           bkgrnd(3x)).  As an optimization, if the scrolling region of the window
           is  the  entire screen, the physical screen may be scrolled at the same
           time; see curscr(3x).

           The cursor does not move.  These functions perform no operation  unless
           scrolling is enabled for the window via scrollok(3x).

## RETURN VALUE

           These functions return ERR upon failure and OK upon success.

           In ncurses, they return ERR if

           o   the curses screen has not been initialized,

           o   (for  functions  taking  a  WINDOW  pointer argument) win is a null
               pointer, or

           o   scrolling is not enabled in the window (as by scrollok(3x)).

## NOTES

           scroll and scrl may be implemented as macros.

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

## PORTABILITY

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

           SVr4 describes a successful return value  only  as  "an  integer  value
           other than ERR".

           SVr4   indicates   that   the   optimization  of  physically  scrolling
           immediately if the scroll region is the entire screen  "is"  performed,
           not  "may  be" performed.  ncurses deliberately does not guarantee that
           this occurs, to leave open the possibility of  better  optimization  of
           multiple scroll actions on the next update.

           Neither  SVr4  curses nor X/Open Curses specify whether these functions
           zero  the  attributes  or  color  pair  identifier  of  the  background
           character.  In ncurses, they do not.

## HISTORY

           4BSD (1980) introduced scroll, defining it as a function.

           SVr3.1  (1987)  added  scrl  and  wscrl,  redefining  scroll as a macro
           wrapping the latter.

## SEE ALSO

           curses(3x), curs_outopts(3x)

    ncurses 6.5                       2025-04-05                   curs_scroll(3x)