curs_pad(3X)

💖 curs_pad(3X) 💖

okay bestie, welcome to the Library calls page for curs_pad(3X) — the one about curses pads. It's giving "windows but make it giant and free-floating," and we're gonna go through every function, parameter, return value, portability tea, and historical lore. no cap. 💅

🌸 NAME 🌸

newpad, subpad, prefresh, pnoutrefresh, pechochar, pecho_wchar — create and display curses pads. 🫶

✨ SYNOPSIS ✨

#include <curses.h>

WINDOW *newpad(int nlines, int ncols);
WINDOW *subpad(WINDOW *parent, int nlines, int ncols,
      int begin_y, int begin_x);

int prefresh(WINDOW *pad, int pminrow, int pmincol,
      int sminrow, int smincol, int smaxrow, int smaxcol);
int pnoutrefresh(WINDOW *pad, int pminrow, int pmincol,
      int sminrow, int smincol, int smaxrow, int smaxcol);

int pechochar(WINDOW *pad, chtype ch);
int pecho_wchar(WINDOW *pad, const cchar_t *wch);

🌈 DESCRIPTION 🌈

A curses pad is basically a window's cooler, less boxed-in cousin: it is not restricted by the screen size, and it is not necessarily associated with a particular part of the screen. Use pads when you need a large window but only part of it should be visible on screen. Also important: pads are not automatically refreshed by scrolling or input-echoing operations. 🙈

bestie, do not try to refresh a pad with wrefresh(3X) — use prefresh or pnoutrefresh instead. periodt. 💅

🦋 newpad 🦋

newpad births a brand-new pad data structure and hands you a pointer to it; you tell it how many lines (nlines) and columns (ncols) you want. slay. ✨

🦋 subpad 🦋

subpad makes a subwindow inside a pad and returns a pointer to it, sized by nlines lines and ncols columns. Unlike subwin(3X), which uses screen coordinates, the new pad is placed at position (begin_y, begin_x) relative to its parent. So yes, changes made to one pad can affect both — they're linked like that. 🫶

When you're working with a subpad, you'll often need to call touchwin(3X) or touchline(3X) on parent before calling prefresh. Don't skip that, bestie. 😭

🦋 prefresh, pnoutrefresh 🦋

prefresh and pnoutrefresh are analogous to wrefresh(3X) and wnoutrefresh(3X) except that they operate on pads rather than windows. They need extra parameters to say which portions of the pad and screen are involved.

• pminrow and pmincol specify the upper left-hand corner of a rectangular view of the pad.
• sminrow, smincol, smaxrow, and smaxcol specify the vertices of the rectangle to be displayed on the screen.

The lower right-hand corner of the pad rectangle is calculated from the screen coordinates, because the rectangles gotta be the same size. Both rectangles must be entirely contained within their respective structures. And if any of these parameters go negative, curses treats them as zero. 🧚

🦋 pechochar 🦋

pechochar is functionally equivalent to calling waddch(3X) followed by prefresh. It basically whispers to the curses optimizer that only a single character is going out; a considerable performance benefit may be thus enjoyed. The spot where ch gets written to the pad is what populates the arguments to prefresh. 🔥

🦋 pecho_wchar 🦋

pecho_wchar is functionally equivalent to calling wadd_wch(3X) followed by prefresh. It basically whispers to the curses optimizer that only a single wide character is going out; a considerable performance benefit may be thus enjoyed. The spot where wch gets written to the pad is what populates the arguments to prefresh. 🌟

💜 RETURN VALUE 💜

Integer-returning functions hand back ERR when they fail and OK when they succeed. 💀

Pointer-returning functions give you a null pointer if things go bad. 🫶

In this implementation specifically:

• prefresh and pnoutrefresh — return ERR when the window pointer is null, when the window isn't actually a pad, when the refresh area goes off-screen, or when the minimum coordinates are greater than the maximum.
• pechochar — returns ERR if the window isn't actually a pad, and the associated call to wechochar returns ERR.
• pecho_wchar — returns ERR if the window isn't actually a pad, and the associated call to wecho_wchar returns ERR.

🎀 NOTES 🎀

Fun fact: pechochar may be implemented as a macro. 📝

curses docs have traditionally been weirdly shy about explaining why it's called a “pad.” Back around 1981, the Apollo Aegis workstation operating system supported a graphical pad feature. 🕰️

• Those graphical pads could be much larger than the computer's display.
• Read-only output from a command could be scrolled back so you could inspect it and select text from the pad.

Those two uses might be related, iykyk. 👀

🌍 PORTABILITY 🌍

X/Open Curses Issue 4 is where these functions are described, and it doesn't specify any error conditions for them. ✨

SVr4 is vague about success: it only says “an integer value other than ERR”. 👑

What subpad does when the parent window isn't a pad? Undocumented. And the vendor Unix implementations don't check it either. 🚩

• SVr4 curses's newpad flips a flag in the WINDOW structure to say “yep, this is a pad.” But it only actually uses that info in waddch (to decide whether to call wrefresh) and wscrl (to avoid scrolling a pad); its wrefresh doesn't check the flag to make sure a pad got properly updated.
• Solaris xcurses does check whether a window is a pad in its wnoutrefresh, and returns ERR if it is. But it only sets the flag on subwindows when the parent window is a pad. Its newpad doesn't set this information. So the check never fails. And it makes no comparable check in pnoutrefresh — though lol, a comment in the source code says the missing check was an MKS extension.
• NetBSD 7 curses sets a WINDOW structure flag for newpad and subpad, which helps it tell wnoutrefresh and pnoutrefresh apart. It doesn't check the case where a subwindow gets created in a pad with subwin or derwin. Its dupwin gives you a regular window when it duplicates a pad. Same energy with its getwin: it always returns a window, even if the saved data came from a pad.

ncurses: 🌈

• it sets a flag in the WINDOW structure for newpad and subpad,
• it lets a subwin or derwin call succeed with a pad parent by forcing the subwindow to be a pad,
• it checks in both wnoutrefresh and pnoutrefresh so pads and windows are handled distinctly, and
• it makes sure dupwin and getwin treat pads versus windows consistently.

📜 HISTORY 📜

SVr2 (1984) introduced newpad, prefresh, and pnoutrefresh, with just one line of docs each. 🕰️

SVr3 (1987) added subpad and pechochar, and gave us more extensive documentation. 💖

The System V Interface Definition, Version 4 (1995), specified a function named pechowchar. That was a later addition to SVr4.x and didn't appear in the first SVr4 (1989). It differs from X/Open's later pecho_wchar because its wstr parameter was a chtype instead of a wchar_t, and it wasn't const-qualified. 📚

👀 SEE ALSO 👀

curses(3X), curs_addch(3X), curs_refresh(3X), curs_touch(3X)

---

xoxo, bestie — this page is from ncurses 6.6, dated 2026-04-18, and it's the curs_pad(3X) manual page. slay and happy padding 💅🎀🦋