curs_scroll(3X)

✨ curs_scroll — scroll, scrl, wscrl ✨

okay bestie, so this is a page from the ncurses library calls era, and it's literally all about making a curses window do the little scroll-y thing 💅

---

🌸 NAME 🌸

scroll, scrl, wscrl — the trio that scrolls a curses window up or down, no cap

---

🎀 SYNOPSIS 🎀

#include <curses.h>

int scroll(WINDOW * win);

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

---

💖 DESCRIPTION 💖

So scroll does the most: it scrolls the window you hand it up by one single line. Translated into math-girl terms: every visible line we might number i becomes line i-1. iconic.

Then wscrl and scrl are the flexible ones — they scroll the window you specify, or stdscr respectively, and they go up or down depending on the sign of n:

• For positive n, line i+n becomes i (that's scrolling up);
• For negative n, line i-n becomes i (that's scrolling down).

A line that scrolls past the window boundaries? Gone. Poof. disappears. And curses fills the new line popping up on the opposite boundary with the background character — go check bkgd(3X) for that (and if you're on the wide-character API, it's bkgrnd(3X) for you 🫶).

Now here's a cute little optimization moment: if the scrolling region of the window happens to be the entire screen, the physical screen may get scrolled at the same time — peep curscr(3X) for the deets.

The cursor does not move. periodt. 🙈

Also, these functions literally do nothing unless scrolling is enabled for the window via scrollok(3X). So if you forgot that, you're gonna be sitting there like… why is nothing happening 😭

---

🌈 RETURN VALUE 🌈

They return ERR when it goes wrong and OK when it goes right. simple as that 💅

In ncurses, they return ERR if:

• the curses screen has not been initialized,
• (for the functions that take a WINDOW pointer argument) win is a null pointer, or
• scrolling is not enabled in the window (as by scrollok(3X)).

---

🦋 NOTES 🦋

scroll and scrl may be implemented as macros. sneaky but valid.

And here's the quirky lore: unusually, there is no wscroll function. scroll just behaves like you'd expect wscroll to, accepting a WINDOW pointer argument. the main character energy of it all.

---

⭐ PORTABILITY ⭐

X/Open Curses Issue 4 describes these functions. It specifies no error conditions for them, so do with that what you will.

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

SVr4 says 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. it's giving strategic.

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

---

👑 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)

---

and that's the whole page, bestie 🫶 this was ncurses 6.6, dated 2025-04-05, and it lives at the curs_scroll(3X) address — no cap, go scroll something ✨