pad(3NCURSES)

💖 pad(3NCURSES) — the library calls that let you build enormous windows and peek at just a slice 💖

okay bestie, settle in, because this one's about pads — the glow-up of windows in ncurses (the library calls, that's the 3NCURSES part) ✨

---

🌸 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 🦋

so a curses pad is literally just a window, except it said "no ❌" to the screen-size rules and it's not tied to any one part of the screen. it's giving main character energy that refuses to be contained 💅

use pads when you need a HUGE window but only a little piece of it should be visible on screen. and heads up: pads do not get auto-refreshed by scrolling or input-echoing operations. they mind their own business, fr fr.

🚨 also, you cannot refresh a pad with wrefresh(3NCURSES). use prefresh or pnoutrefresh instead. do not try it. it will not slay.

✨ newpad ✨

newpad creates a brand-new pad data structure and returns a pointer to it, with the number of lines you asked for (nlines) and columns you asked for (ncols). iconic. no notes.

🎀 subpad 🎀

subpad creates a subwindow inside a pad and returns a pointer to it, again with the lines (nlines) and columns (ncols) you want.

but here's the twist 🌀 — unlike subwin(3NCURSES), which uses screen coordinates, the new pad gets placed at position (begin_y, begin_x) relative to its parent. so they're like… linked. changes made to one pad can affect both. it's giving shared custody 😭

and when you're operating on a subpad, you'll often have to call touchwin(3NCURSES) or touchline(3NCURSES) on the parent before you call prefresh. don't forget, bestie, or you'll be staring at a sad stale screen.

💅 prefresh, pnoutrefresh 💅

prefresh and pnoutrefresh are the pad-flavored twins of wrefresh(3NCURSES) and wnoutrefresh(3NCURSES) — same vibe, but they operate on pads instead of windows.

the catch? they need extra parameters to tell them which portions of the pad and the screen are involved, because how else would anything know 👀

• 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 rectangle to be displayed in the pad gets calculated from the screen coordinates, because the two rectangles have to be the same size — matching set, obviously 💞

both rectangles must be entirely contained within their respective structures. and if you pass negative values for any of these parameters, curses just treats them as zero. no drama, just zero.

🍓 pechochar 🍓

pechochar does exactly the same thing as calling waddch(3NCURSES) and then prefresh. literally the same.

but it whispers to the curses optimizer that only a single character is being output, and a considerable performance benefit may be thus enjoyed 🔥 the location of the character ch written to the pad is what populates the arguments to prefresh. efficiency queen 👑

🌈 pecho_wchar 🌈

pecho_wchar is functionally equivalent to calling wadd_wch(3NCURSES) followed by prefresh. it hints to the curses optimizer that only a single wide character is being output, and again, considerable performance benefit may be thus enjoyed 🔥🔥

the location of the character wch written to the pad populates the arguments to prefresh. same energy, wider characters 💜

---

💀 RETURN VALUE 💀

functions that return an int return ERR when things go wrong and OK when they go right. simple as.

functions that return pointers return a null pointer on failure. tragic but true.

and in this here implementation, specifically:

• prefresh and pnoutrefresh — return ERR if the window pointer is null, or if the window is not really a pad, or if the area to refresh extends off-screen, or if the minimum coordinates are greater than the maximum. four separate ways to fail, she contains multitudes 🙈
• pechochar — returns ERR if the window is not really a pad, and the associated call to wechochar returns ERR.
• pecho_wchar — returns ERR if the window is not really a pad, and the associated call to wecho_wchar returns ERR.

---

👑 NOTES 👑

pechochar may be implemented as a macro. just so you know 🫶

okay and here's some lore: curses documentation is traditionally averse to motivating the term "pad". the Apollo Aegis workstation operating system (circa 1981) supported a graphical pad feature. yes, we're going back in time, bestie 🕰️

• these graphical pads could be much larger than the computer's display.
• the read-only output from a command could be scrolled back to inspect and select text from the pad.

the two uses may be related. we simply do not know. iykyk 🤷

---

🧚 PORTABILITY 🧚

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

SVr4 describes a successful return value only as "an integer value other than ERR". vague! mysterious! the minimalism 💀

the behavior of subpad if the parent window is not a pad is undocumented, and it is not checked by the vendor Unix implementations. so… undefined territory, tread carefully.

• SVr4 curses's newpad sets a flag in the WINDOW structure indicating that the window is a pad.
  • however, it uses this information only in waddch (to decide if it should call wrefresh) and wscrl (to avoid scrolling a pad); its wrefresh does not check it to ensure that a pad is properly updated. so the flag is kind of just… vibing there unfollowed.
• Solaris xcurses checks whether a window is a pad in its wnoutrefresh, returning ERR in that case.
  • however, it sets the flag on subwindows only if the parent window is a pad. its newpad does not set this information. consequently, the check never fails. incredible. iconic. useless 🎀
  • it makes no comparable check in pnoutrefresh — though interestingly enough, a comment in the source code states that the lack of a check was an MKS extension.
• NetBSD 7 curses sets a flag in the WINDOW structure for newpad and subpad, aiding itself to distinguish between wnoutrefresh and pnoutrefresh.
  • it does not check for the case where a subwindow is created in a pad using subwin or derwin.
  • its dupwin returns a regular window when duplicating a pad. likewise, its getwin always returns a window, even if the saved data was from a pad.

and then there's ncurses, which simply ate 💅:

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

no cap, that's the whole checklist, and she did all of it 🌟

---

⭐ HISTORY ⭐

SVr2 (1984) introduced newpad, prefresh, and pnoutrefresh, documenting them in a single line each. stingy with the words, generous with the functions.

SVr3 (1987) added subpad and pechochar, and provided more extensive documentation. glow up unlocked.

The System V Interface Definition, Version 4 (1995), specified a function named pechowchar. this was a later addition to SVr4.x, and it does not appear in the first SVr4 (1989). it differs from X/Open's later pecho_wchar in that its wstr parameter was a chtype instead of a wchar_t, and was not const-qualified. history really said "close enough" 😭

---

🌈 SEE ALSO 🌈

• ncurses(3NCURSES)
• addch(3NCURSES)
• refresh(3NCURSES)
• touch(3NCURSES)

---

and that's the whole page, bestie 🫶 this was ncurses 6.6, dated 2026-04-18 — go forth and refresh your pads responsibly 💖✨🎀