# curs_pad 3x 2026-04-18 ncurses 6.6 Library calls

    curs_pad(3x)                     Library calls                    curs_pad(3x)

## 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 like a window, except that it is not restricted by the
           screen size, and is not necessarily associated with a  particular  part
           of  the  screen.   Pads can be used when a large window is needed, only
           part  of  which  is  to  be  visible  on  the  screen.   Pads  are  not
           automatically refreshed by scrolling or input-echoing operations.

           Pads   cannot   be   refreshed   with  wrefresh(3x);  use  prefresh  or
           pnoutrefresh instead.

### newpad

           newpad creates and returns a pointer to a new pad data  structure  with
           the given number of lines, nlines, and columns, ncols.

### subpad

           subpad  creates  and returns a pointer to a subwindow within a pad with
           the  given  number  of  lines,  nlines,  and  columns,  ncols.   Unlike
           subwin(3x),  which  uses  screen  coordinates, the new pad is placed at
           position (begin_y, begin_x) relative to its parent.  Thus, changes made
           to one pad can affect both.  When operating on a subpad,  it  is  often
           necessary  to  call  touchwin(3x)  or  touchline(3x)  on  parent before
           calling prefresh.

### prefresh, pnoutrefresh

           prefresh  and  pnoutrefresh   are   analogous   to   wrefresh(3x)   and
           wnoutrefresh(3x)  except that they operate on pads rather than windows.
           They require additional parameters are needed to indicate what portions
           of the pad and screen are involved.

           o   pminrow and  pmincol  specify  the  upper  left-hand  corner  of  a
               rectangular view of the pad.

           o   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
           is calculated from the screen coordinates, since the rectangles must be
           the same size.  Both rectangles must be entirely contained within their
           respective structures.  curses treats negative values of any  of  these
           parameters as zero.

### pechochar

           pechochar  is functionally equivalent to calling waddch(3x) followed by
           prefresh.  It suggests to the  curses  optimizer  that  only  a  single
           character  is  being  output; a considerable performance benefit may be
           thus enjoyed.  The location of the character ch written to the  pad  is
           used to populate the arguments to prefresh.

### pecho_wchar

           pecho_wchar is functionally equivalent to calling wadd_wch(3x) followed
           by  prefresh.   It  suggests to the curses optimizer that only a single
           wide character is being output; a considerable performance benefit  may
           be  thus enjoyed.  The location of the character wch written to the pad
           is used to populate the arguments to prefresh.

## RETURN VALUE

           Functions that return an integer return ERR upon failure  and  OK  upon
           successful completion.

           Functions that return pointers return a null pointer on failure.

           In this implementation

              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.

              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.

           curses  documentation  is  traditionally  averse to motivating the term
           "pad".  The Apollo Aegis  workstation  operating  system  (circa  1981)
           supported a graphical pad feature.

           o   These  graphical  pads  could  be  much  larger than the computer's
               display.

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

## 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".

           The  behavior  of  subpad  if  the  parent  window  is  not  a  pad  is
           undocumented, and is not checked by the vendor Unix implementations.

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

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

               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.

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

           ncurses:

           o   sets a flag in the WINDOW structure for newpad and subpad,

           o   allows  a  subwin  or derwin call to succeed having a pad parent by
               forcing the subwindow to be a pad,

           o   checks in both wnoutrefresh and pnoutrefresh to  ensure  that  pads
               and windows are handled distinctly, and

           o   ensures   that   dupwin   and  getwin  treat  pads  versus  windows
               consistently.

## HISTORY

           SVr2 (1984) introduced newpad, prefresh, and pnoutrefresh,  documenting
           them in a single line each.

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

           The System V  Interface  Definition,  Version  4  (1995),  specified  a
           function  named  pechowchar.   This was a later addition to SVr4.x, not
           appearing 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.

## SEE ALSO

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

    ncurses 6.6                       2026-04-18                      curs_pad(3x)