# curs_pad 3x 2025-08-23 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, and
           set errno to ENOMEM.

           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                       2025-08-23                      curs_pad(3x)