unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

CURSES(3V)                                                          CURSES(3V)



NAME
       curses - System V terminal screen handling and optimization package

SYNOPSIS
       The curses manual page is organized as follows:

       In SYNOPSIS

              o  compiling information

              o  summary of parameters used by curses routines

       In SYSTEM V SYNOPSIS:

              o  compiling information

       In DESCRIPTION and SYSTEM V DESCRIPTION:

              o  An overview of how curses routines should be used

       In  ROUTINES,  descriptions  of  curses  routines are grouped under the
       appropriate topics:

              o  Overall Screen Manipulation

              o  Window and Pad Manipulation

              o  Output

              o  Input

              o  Output Options Setting

              o  Input Options Setting

              o  Environment Queries

              o  Low-level Curses Access

              o  Miscellaneous

              o  Use of curscr

       In SYSTEM V ROUTINES, descriptions of curses routines are grouped under
       the appropriate topics:

              o  Overall Screen Manipulation

              o  Window and Pad Manipulation

              o  Output

              o  Input

              o  Output Options Setting

              o  Input Options Setting

              o  Environment Queries

              o  Soft Labels

              o  Low-level Curses Access

              o  Terminfo-Level Manipulations

              o  Termcap Emulation

              o  Miscellaneous

              o  Use of curscr

       Then come sections on:

              o  SYSTEM V ATTRIBUTES

              o  SYSTEM V FUNCTION KEYS

              o  LINE GRAPHICS

       cc [ flags ] files -lcurses -ltermcap [ libraries ]

       #include <&lt;curses.h>&gt;      (automatically    includes    <&lt;stdio.h>&gt;    and
                                <&lt;unctl.h>&gt;.)

       The parameters in the following list are not global variables.  This is
       a  summary  of the parameters used by the curses library routines.  All
       routines return the int values ERR or OK unless otherwise noted.   Rou-
       tines  that return pointers always return NULL on error.  ERR, OK , and
       NULL are all defined in <&lt;curses.h>&gt;.)  Routines that return integers are
       not listed in the parameter list below.

       bool bf
       char **area,*boolnames[], *boolcodes[], *boolfnames[], *bp
       char *cap, *capname, codename[2], erasechar, *filename, *fmt
       char *keyname, killchar, *label, *longname
       char *name, *numnames[], *numcodes[], *numfnames[]
       char *slk_label, *str, *strnames[], *strcodes[], *strfnames[]
       char *term, *tgetstr, *tigetstr, *tgoto, *tparm, *type
       chtype attrs, ch, horch, vertch
       FILE *infd, *outfd
       int begin_x, begin_y, begline, bot, c, col, count
       int dmaxcol, dmaxrow, dmincol, dminrow, *errret, fildes
       int (*init()), labfmt, labnum, line
       int ms, ncols, new, newcol, newrow, nlines, numlines
       int oldcol, oldrow, overlay
       int p1, p2, p9, pmincol, pminrow, (*putc()), row
       int smaxcol, smaxrow, smincol, sminrow, start
       int tenths, top, visibility, x, y
       SCREEN *new, *newterm, *set_term
       TERMINAL *cur_term, *nterm, *oterm
       va_list varglist
       WINDOW *curscr, *dstwin, *initscr, *newpad, *newwin, *orig
       WINDOW *pad, *srcwin, *stdscr, *subpad, *subwin, *win

SYSTEM V SYNOPSIS
       /usr/5bin/cc [ flag ...]  file ...  -lcurses [ library ...]

       #include <&lt;curses.h>&gt;      (automatically includes <&lt;stdio.h>&gt;, <&lt;termio.h>&gt;,
                                and <&lt;unctrl.h>&gt;).

DESCRIPTION
       These routines give the user a method of updating screens with  reason-
       able  optimization.   They keep an image of the current screen, and the
       user sets up an image of a new one.  Then the refresh() tells the  rou-
       tines  to  make  the current screen look like the new one.  In order to
       initialize the routines, the routine initscr() must  be  called  before
       any  of the other routines that deal with windows and screens are used.
       The routine endwin() should be called before exiting.

SYSTEM V DESCRIPTION
       The curses routines give the  user  a  terminal-independent  method  of
       updating screens with reasonable optimization.

       In order to initialize the routines, the routine initscr() or newterm()
       must be called before any of the other routines that deal with  windows
       and  screens  are  used.   Three exceptions are noted where they apply.
       The routine endwin() must be called before exiting.  To get  character-
       at-a-time  input  without  echoing,  (most interactive, screen oriented
       programs want this) after calling initscr() you should call `cbreak ();
       noecho  ();'  Most  programs  would  additionally  call `nonl (); intr-
       flush(stdscr, FALSE); keypad(stdscr, TRUE);'.

       Before a curses program is run, a terminal's TAB stops  should  be  set
       and  its  initialization strings, if defined, must be output.  This can
       be done by executing the tset command in your .profile or .login  file.
       For  further  details, see tset(1) and the Tabs and Initialization sub-
       section of terminfo(5V).

       The curses library contains routines that  manipulate  data  structures
       called  windows  that  can  be  thought of as two-dimensional arrays of
       characters representing all or part of a terminal  screen.   A  default
       window  called  stdscr  is  supplied, which is the size of the terminal
       screen.  Others may be created with newwin().  Windows are referred  to
       by  variables  declared  as  WINDOW  *;  the  type WINDOW is defined in
       <curses.h> to be a C structure.  These data structures are  manipulated
       with  routines  described  below, among which the most basic are move()
       and addch().  More general versions of these routines are included with
       names beginning with w, allowing you to specify a window.  The routines
       not beginning with w usually affect stdscr.  Then refresh() is  called,
       telling  the routines to make the user's terminal screen look like std-
       scr.  The characters in a window are actually of type chtype,  so  that
       other  information  about  the  character  may also be stored with each
       character.

       Special windows called pads may also be manipulated.  These are windows
       that  are  not constrained to the size of the screen and whose contents
       need not be displayed completely.   See  the  description  of  newpad()
       under Window and Pad Manipulation for more information.

       In  addition  to drawing characters on the screen, video attributes may
       be included that cause the characters to  show  up  in  modes  such  as
       underlined  or  in reverse video on terminals that support such display
       enhancements.  Line drawing characters may be specified to  be  output.
       On input, curses is also able to translate arrow and function keys that
       transmit escape sequences into single values.   The  video  attributes,
       line  drawing  characters,  and  input  values  use  names,  defined in
       <curses.h>, such as A_REVERSE, ACS_HLINE, and KEY_LEFT.

       curses also defines the WINDOW * variable, curscr, which is  used  only
       for certain low-level operations like clearing and redrawing a garbaged
       screen.  curscr can be used in only a  few  routines.   If  the  window
       argument  to  clearok() is curscr, the next call to wrefresh() with any
       window will clear and repaint the screen from scratch.  If  the  window
       argument to wrefresh() is curscr, the screen in immediately cleared and
       repainted from scratch.  This is how most programs  would  implement  a
       "repaint-screen"  function.   More  information on using curscr is pro-
       vided where its use is appropriate.

       The environment variables LINES and COLUMNS  may  be  set  to  override
       curses's idea of how large a screen is.

       If  the  environment  variable  TERMINFO  is defined, any program using
       curses will check for a local terminal definition  before  checking  in
       the  standard  place.  For example, if the environment variable TERM is
       set  to  sun,  then  the  compiled  terminal  definition  is  found  in
       /usr/share/lib/terminfo/s/sun.   The  s is copied from the first letter
       of sun to avoid creation of huge directories.)  However, if TERMINFO is
       set to $HOME/myterms, curses will first check $HOME/myterms/s/sun, and,
       if that fails, will then check /usr/share/lib/terminfo/s/sun.  This  is
       useful for developing experimental definitions or when write permission
       on /usr/share/lib/terminfo is not available.

       The integer variables LINES and COLS are  defined  in  <curses.h>,  and
       will  be  filled in by initscr() with the size of the screen.  For more
       information, see the subsection Terminfo-Level Manipulations.  The con-
       stants  TRUE and FALSE have the values 1 and 0, respectively.  The con-
       stants ERR and OK are returned by routines to indicate whether the rou-
       tine  successfully  completed.   These  constants  are  also defined in
       <&lt;curses.h>&gt;.

ROUTINES
       Many of the following routines have two or more versions.  The routines
       prefixed  with w require a window argument.  The routines prefixed with
       p require a pad argument.  Those without a prefix generally use stdscr.

       The routines prefixed with mv require y and x coordinates  to  move  to
       before performing the appropriate action.  The mv routines imply a call
       to move() before the call to the other routine.  The window argument is
       always  specified  before  the coordinates.  y always refers to the row
       (of the window), and x always refers to the  column.   The  upper  left
       corner is always (0,0), not (1,1).  The routines prefixed with mvw take
       both a window argument and y and x coordinates.

       In each case, win is the window affected and pad is the  pad  affected.
       (win  and  pad  are  always of type WINDOW *.)  Option-setting routines
       require a boolean flag bf with the value TRUE or FALSE.  (bf is  always
       of  type  bool.)   The  types  WINDOW,  bool, and chtype are defined in
       <curses.h> (see SYNOPSIS for a summary  of  what  types  all  variables
       are).

       All  routines  return  either the integer ERR or the integer OK, unless
       otherwise noted.  Routines that return pointers always return  NULL  on
       error.

   Overall Screen Manipulation
       WINDOW *initscr()   The  first  routine  called should almost always be
                           initscr().  The  exceptions  are  slk_init(),  fil-
                           ter(),  and  ripoffline().  This will determine the
                           terminal type and initialize all curses data struc-
                           tures.  initscr() also arranges that the first call
                           to refresh() will  clear  the  screen.   If  errors
                           occur,  initscr()  will  write an appropriate error
                           message to standard error and  exit;  otherwise,  a
                           pointer  to  stdscr  is  returned.   If the program
                           wants an indication of error conditions,  newterm()
                           should  be  used  instead  of initscr().  initscr()
                           should only be called once per application.

       endwin()            A program should always call endwin() before  exit-
                           ing or escaping from curses mode temporarily, to do
                           a shell escape  or  system(3)  call,  for  example.
                           This routine will restore termio(4) modes, move the
                           cursor to the lower left corner of the  screen  and
                           reset the terminal into the proper non-visual mode.
                           To resume after a temporary escape, call wrefresh()
                           or doupdate().

   Window and Pad Manipulation
       refresh()

       wrefresh (win)      These   routines  (or  prefresh(),  pnoutrefresh(),
                           wnoutrefresh(), or doupdate()) must  be  called  to
                           write  output  to  the terminal, as most other rou-
                           tines  merely  manipulate  data  structures.   wre-
                           fresh()  copies  the  named  window to the physical
                           terminal  screen,  taking  into  account  what   is
                           already  there  in  order to minimize the amount of
                           information that's sent  to  the  terminal  (called
                           optimization).   refresh()  does  the  same  thing,
                           except it uses stdscr as a default window.   Unless
                           leaveok()  has been enabled, the physical cursor of
                           the terminal is left at the location  of  the  win-
                           dow's  cursor.   The number of characters output to
                           the terminal is returned.
                           Note: refresh() is a macro.

       WINDOW *newwin (nlines, ncols, begin_y, begin_x)
                           Create and return a pointer to a  new  window  with
                           the  given  number  of lines (or rows), nlines, and
                           columns, ncols.  The upper left corner of the  win-
                           dow  is at line begin_y, column begin_x.  If either
                           nlines or ncols is 0, they will be set to the value
                           of  lines-begin_y  and  cols-begin_x.   A new full-
                           screen    window    is    created    by     calling
                           newwin(0,0,0,0).

       mvwin (win, y, x)   Move  the window so that the upper left corner will
                           be at position (y, x).  If the move would cause the
                           window to be off the screen, it is an error and the
                           window is not moved.

       WINDOW *subwin (orig, nlines, ncols, begin_y, begin_x)
                           Create and return a pointer to a  new  window  with
                           the  given  number  of lines (or rows), nlines, and
                           columns,  ncols.   The  window  is  at  position  (
                           begin_y,  begin_x) on the screen.  This position is
                           relative to the screen, and not to the window orig.
                           The  window  is  made  in  the middle of the window
                           orig, so that  changes  made  to  one  window  will
                           affect  both  windows.   When  using  this routine,
                           often it will be necessary to  call  touchwin()  or
                           touchline() on orig before calling wrefresh.

        delwin (win)       Delete  the  named  window,  freeing  up all memory
                           associated with it.  In  the  case  of  overlapping
                           windows,  subwindows  should  be deleted before the
                           main window.

   Output
       These routines are used to "draw" text on windows.

       addch (ch)

       waddch (win, ch)

       mvaddch (y, x, ch)

       mvwaddch (win, y, x, ch)
                           The character ch is put into the window at the cur-
                           rent cursor position of the window and the position
                           of the window cursor is advanced.  Its function  is
                           similar  to  that  of putchar() (see putc(3s)).  At
                           the right margin,  an  automatic  newline  is  per-
                           formed.   At the bottom of the scrolling region, if
                           scrollok() is enabled, the scrolling region will be
                           scrolled up one line.

                           If  ch  is a TAB, NEWLINE, or backspace, the cursor
                           will be moved appropriately within the  window.   A
                           NEWLINE  also does a clrtoeol() before moving.  TAB
                           characters are considered to  be  at  every  eighth
                           column.   If  ch  is  another control character, it
                           will be drawn in  the  CTRL-X  notation.   (Calling
                           winch()  after  adding a control character will not
                           return the  control  character,  but  instead  will
                           return  the  representation  of the control charac-
                           ter.)

                           Video attributes can be combined with  a  character
                           by  or-ing  them  into  the  parameter.   This will
                           result in these attributes  also  being  set.   The
                           intent here is that text, including attributes, can
                           be copied from one place to  another  using  inch()
                           and addch().  See standout(), below.

                           Note:  ch is actually of type chtype, not a charac-
                           ter.

                           Note:  addch(),  mvaddch(),  and   mvwaddch()   are
                           macros.

       addstr (str)

       waddstr (win, str)

       mvwaddstr (win, y, x, str)

       mvaddstr (y, x, str)
                           These  routines  write  all  the  characters of the
                           null-terminated character string str on  the  given
                           window.   This  is  equivalent  to calling waddch()
                           once for each character in the string.

                           Note: addstr(),  mvaddstr(),  and  mvwaddstr()  are
                           macros.

       box (win, vertch, horch)
                           A  box is drawn around the edge of the window, win.
                           vertch and horch are the characters the box  is  to
                           be  drawn  with.   If  vertch and horch are 0, then
                           appropriate  default  characters,   ACS_VLINE   and
                           ACS_HLINE, will be used.

                           Note: vertch and horch are actually of type chtype,
                           not characters.

       erase()

       werase (win)        These routines copy blanks to every position in the
                           window.

                           Note: erase() is a macro.

       clear()

       wclear (win)        These  routines  are like erase() and werase(), but
                           they also call clearok(), arranging that the screen
                           will be cleared completely on the next call to wre-
                           fresh()  for  that  window,  and   repainted   from
                           scratch.

                           Note: clear() is a macro.

       clrtobot()

       wclrtobot (win)     All  lines  below  the  cursor  in  this window are
                           erased.  Also, the current line to the right of the
                           cursor, inclusive, is erased.

                           Note: clrtobot() is a macro.

       clrtoeol()

       wclrtoeol (win)     The current line to the right of the cursor, inclu-
                           sive, is erased.

                           Note: clrtoeol() is a macro.

       delch()

       wdelch (win)

       mvdelch (y, x)

       mvwdelch (win, y, x)
                           The character under the cursor  in  the  window  is
                           deleted.   All  characters to the right on the same
                           line are moved to the left  one  position  and  the
                           last  character on the line is filled with a blank.
                           The cursor position does not change  (after  moving
                           to  (y, x), if specified).  This does not imply use
                           of the hardware "delete-character" feature.

                           Note:  delch(),  mvdelch(),  and   mvwdelch()   are
                           macros.

       deleteln()

       wdeleteln (win)     The line under the cursor in the window is deleted.
                           All lines below the current line are moved  up  one
                           line.   The  bottom  line of the window is cleared.
                           The cursor position does not change.  This does not
                           imply use of the hardware "delete-line" feature.

                           Note: deleteln() is a macro.

       getyx (win, y, x)   The  cursor position of the window is placed in the
                           two integer variables y and x.  This is implemented
                           as a macro, so no `&&amp;' is necessary before the vari-
                           ables.

       insch (ch)

       winsch (win, ch)

       mvwinsch (win, y, x, ch)

       mvinsch (y, x, ch)  The character ch is inserted before  the  character
                           under  the cursor.  All characters to the right are
                           moved one SPACE to the right, possibly  losing  the
                           rightmost  character of the line.  The cursor posi-
                           tion does not change (after moving to  (y,  x),  if
                           specified).   This  does not imply use of the hard-
                           ware "insert-character" feature.

                           Note: ch is actually of type chtype, not a  charac-
                           ter.

                           Note:   insch(),   mvinsch(),  and  mvwinsch()  are
                           macros.

       insertln()

       winsertln (win)     A blank line is inserted above the current line and
                           the  bottom  line is lost.  This does not imply use
                           of the hardware "insert-line" feature.

                           Note: insertln() is a macro.

       move (y, x)

       wmove (win, y, x)   The cursor associated with the window is  moved  to
                           line  (row)  y,  column  x.  This does not move the
                           physical cursor of the terminal until refresh()  is
                           called.   The position specified is relative to the
                           upper left corner of the window, which is (0, 0).

                           Note: move() is a macro.

       overlay (srcwin, dstwin)

       overwrite (srcwin, dstwin)
                           These routines overlay srcwin  on  top  of  dstwin;
                           that  is, all text in srcwin is copied into dstwin.
                           scrwin and dstwin need not be the same  size;  only
                           text  where the two windows overlap is copied.  The
                           difference is  that  overlay()  is  non-destructive
                           (blanks  are  not  copied),  while  overwrite()  is
                           destructive.

       printw (fmt [, arg...])

       wprintw (win, fmt [, arg...])

       mvprintw (y, x, fmt [, arg...])

       mvwprintw (win, y, x, fmt [, arg...])
                           These routines are analogous  to  printf(3V).   The
                           string  that  would  be  output  by  printf(3V)  is
                           instead output using waddstr() on the given window.

       scroll (win)        The window is scrolled up one line.  This  involves
                           moving  the lines in the window data structure.  As
                           an optimization, if the window is  stdscr  and  the
                           scrolling region is the entire window, the physical
                           screen will be scrolled at the same time.

       touchwin (win)

       touchline (win, start, count)
                           Throw away all optimization information about which
                           parts  of the window have been touched, by pretend-
                           ing that the entire window has been drawn on.  This
                           is  sometimes necessary when using overlapping win-
                           dows, since a change to one window will affect  the
                           other  window,  but the records of which lines have
                           been changed in the other window will  not  reflect
                           the  change.   touchline() only pretends that count
                           lines have been changed, beginning with line start.

   Input
       getch()

       wgetch (win)

       mvgetch (y, x)

       mvwgetch (win, y, x)
                           A character is read from  the  terminal  associated
                           with  the  window.  In NODELAY mode, if there is no
                           input waiting, the value ERR is returned.  In DELAY
                           mode, the program will hang until the system passes
                           text through to the program.  Depending on the set-
                           ting  of cbreak(), this will be after one character
                           (CBREAK mode), or after the first newline (NOCBREAK
                           mode).   In  HALF-DELAY mode, the program will hang
                           until a character is typed or the specified timeout
                           has  been  reached.   Unless noecho() has been set,
                           the character will also be echoed into  the  desig-
                           nated  window.  No refresh() will occur between the
                           move() and the getch()  done  within  the  routines
                           mvgetch() and mvwgetch().

                           When   using   getch(),   wgetch(),  mvgetch(),  or
                           mvwgetch(),  do  not   set   both   NOCBREAK   mode
                           (nocbreak())  and  ECHO  mode  (echo()) at the same
                           time.  Depending  on  the  state  of  the  terminal
                           driver  when  each  character is typed, the program
                           may produce undesirable results.

                           If keypad (win, TRUE) has been called, and a  func-
                           tion  key  is  pressed, the token for that function
                           key will be returned instead of the raw characters.
                           See keypad() under Input Options Setting.  Possible
                           function keys are defined in <curses.h> with  inte-
                           gers  beginning  with  0401, whose names begin with
                           KEY_.  If a character is received that could be the
                           beginning  of  a  function  key  (such  as escape),
                           curses will set a timer.  If the remainder  of  the
                           sequence  is  not  received  within  the designated
                           time, the character will be passed through,  other-
                           wise  the function key value will be returned.  For
                           this reason, on many terminals,  there  will  be  a
                           delay  after  a  user presses the escape key before
                           the escape is returned to the program.   Use  by  a
                           programmer of the escape key for a single character
                           routine  is  discouraged.   Also  see   notimeout()
                           below.

                           Note:   getch(),   mvgetch(),  and  mvwgetch()  are
                           macros.

       getstr (str)

       wgetstr (win, str)

       mvgetstr (y, x, str)

       mvwgetstr (win, y, x, str)
                           A series of calls to getch() is made, until a  new-
                           line,  carriage  return,  or enter key is received.
                           The resulting value is placed in the  area  pointed
                           at  by the character pointer str.  The user's erase
                           and  kill  characters  are  interpreted.    As   in
                           mvgetch(),  no refresh() is done between the move()
                           and getstr() within  the  routines  mvgetstr()  and
                           mvwgetstr().

                           Note:  getstr(),  mvgetstr(),  and  mvwgetstr() are
                           macros.

       inch()

       winch (win)

       mvinch (y, x)

       mvwinch (win, y, x) The character, of type chtype, at the current posi-
                           tion  in  the  named  window  is  returned.  If any
                           attributes are set for that position, their  values
                           will  be OR'ed into the value returned.  The prede-
                           fined  constants   A_CHARTEXT   and   A_ATTRIBUTES,
                           defined in <curses.h>, can be used with the C logi-
                           cal AND (&) operator to extract  the  character  or
                           attributes alone.

                           Note:  inch(), winch(), mvinch(), and mvwinch() are
                           macros.

       scanw (fmt[,arg...]")

       wscanw (win, fmt [, arg...])

       mvscanw (y, x, fmt [, arg...])

       mvwscanw (win, y, x, fmt [, arg...])
                           These routines correspond to scanf(3V), as do their
                           arguments  and  return values.  wgetstr() is called
                           on the window, and the resulting line  is  used  as
                           input for the scan.

   Output Options Setting
       These  routines  set  options within curses that deal with output.  All
       options are initially FALSE, unless otherwise stated.  It is not neces-
       sary to turn these options off before calling endwin().

       clearok (win, bf)   If  enabled  (bf  is  TRUE),  the next call to wre-
                           fresh() with this window will clear the screen com-
                           pletely  and redraw the entire screen from scratch.
                           This is useful when the contents of the screen  are
                           uncertain,  or  in  some  cases for a more pleasing
                           visual effect.

       idlok (win, bf)     If enabled (bf is TRUE), curses will consider using
                           the hardware "insert/delete-line" feature of termi-
                           nals so  equipped.   If  disabled  (bf  is  FALSE),
                           curses  will  very  seldom  use  this feature.  The
                           "insert/delete-character" feature is always consid-
                           ered.   This  option should be enabled only if your
                           application needs "insert/delete-line",  for  exam-
                           ple,  for  a  screen  editor.   It  is  disabled by
                           default because "insert/delete-line"  tends  to  be
                           visually  annoying  when used in applications where
                           it is not really needed.   If  "insert/delete-line"
                           cannot be used, curses will redraw the changed por-
                           tions of all lines.

       leaveok (win, bf)   Normally, the hardware cursor is left at the  loca-
                           tion  of  the  window cursor being refreshed.  This
                           option allows the cursor to be  left  wherever  the
                           update  happens  to  leave  it.   It  is useful for
                           applications where the cursor is not used, since it
                           reduces  the need for cursor motions.  If possible,
                           the cursor is made invisible when  this  option  is
                           enabled.

       scrollok (win, bf)  This  option  controls what happens when the cursor
                           of a window is moved off the edge of the window  or
                           scrolling region, either from a newline on the bot-
                           tom line, or typing the last character of the  last
                           line.   If  disabled  (bf  is FALSE), the cursor is
                           left on the bottom line at the location  where  the
                           offending character was entered.  If enabled (bf is
                           TRUE), wrefresh() is called on the window, and then
                           the  physical  terminal  and window are scrolled up
                           one line.  Note:  in  order  to  get  the  physical
                           scrolling effect on the terminal, it is also neces-
                           sary to call idlok().

       nl()

       nonl()              These routines control whether  NEWLINE  is  trans-
                           lated  into  RETURN  and  LINEFEED  on  output, and
                           whether RETURN is translated into NEWLINE on input.
                           Initially, the translations do occur.  By disabling
                           these translations using nonl(), curses is able  to
                           make better use of the linefeed capability, result-
                           ing in faster cursor motion.

   Input Options Setting
       These routines set options within curses that  deal  with  input.   The
       options  involve using ioctl(2) and therefore interact with curses rou-
       tines.  It is not necessary to turn these options  off  before  calling
       endwin().

       For more information on these options, refer to

       cbreak()

       nocbreak()          These two routines put the terminal into and out of
                           CBREAK mode, respectively.  In CBREAK mode, charac-
                           ters typed by the user are immediately available to
                           the program and erase/kill character processing  is
                           not  performed.   When  in  NOCBREAK  mode, the tty
                           driver will buffer characters typed until a NEWLINE
                           or  RETURN  is  typed.   Interrupt and flow-control
                           characters  are  unaffected  by  this   mode   (see
                           termio(4)).   Initially the terminal may or may not
                           be in CBREAK mode, as it is inherited, therefore, a
                           program  should call cbreak() or nocbreak() explic-
                           itly.  Most interactive programs using curses  will
                           set CBREAK mode.

                           Note:  cbreak() overrides raw().  See getch() under
                           Input for a discussion of how these routines inter-
                           act with echo() and noecho().

       echo()

       noecho()            These  routines control whether characters typed by
                           the user are echoed by getch() as they  are  typed.
                           Echoing  by  the tty driver is always disabled, but
                           initially getch() is in ECHO  mode,  so  characters
                           typed are echoed.  Authors of most interactive pro-
                           grams prefer to do their  own  echoing  in  a  con-
                           trolled  area of the screen, or not to echo at all,
                           so they disable echoing by calling  noecho().   See
                           getch()  under  Input for a discussion of how these
                           routines interact with cbreak() and nocbreak().

       raw()

       noraw()             The terminal is placed into or  out  of  RAW  mode.
                           RAW mode is similar to CBREAK mode, in that charac-
                           ters typed are immediately passed  through  to  the
                           user  program.   The  differences  are  that in RAW
                           mode, the interrupt, quit, suspend, and  flow  con-
                           trol  characters  are passed through uninterpreted,
                           instead of generating  a  signal.   RAW  mode  also
                           causes 8-bit input and output.  The behavior of the
                           BREAK key depends on other  bits  in  the  terminal
                           driver that are not set by curses.

   Environment Queries
       baudrate()          Returns the output speed of the terminal.  The num-
                           ber returned is in bits per  second,  for  example,
                           9600, and is an integer.

       char erasechar()    The user's current erase character is returned.

       char killchar()     The user's current line-kill character is returned.

       char *longname()    This  routine  returns  a  pointer to a static area
                           containing a verbose  description  of  the  current
                           terminal.  The maximum length of a verbose descrip-
                           tion is 128 characters.  It is defined  only  after
                           the  call  to  initscr() or newterm().  The area is
                           overwritten by each call to newterm()  and  is  not
                           restored  by  set_term(),  so  the  value should be
                           saved between calls to newterm() if  longname()  is
                           going to be used with multiple terminals.

   Low-Level curses Access
       The  following  routines  give low-level access to various curses func-
       tionality.  These routines typically would be used  inside  of  library
       routines.

       resetty()

       savetty()           These  routines  save  and restore the state of the
                           terminal modes.  savetty() saves the current  state
                           of  the terminal in a buffer and resetty() restores
                           the state to what  it  was  at  the  last  call  to
                           savetty().

   Miscellaneous
       unctrl (c)          This macro expands to a character string which is a
                           printable representation of the character c.   Con-
                           trol  characters  are displayed in the ^X notation.
                           Printing characters are displayed as is.

                           unctrl() is a macro, defined in  <unctrl.h>,  which
                           is automatically included by <curses.h>.

       flusok(win,boolf)   set flush-on-refresh flag for win

       getcap(name)        get terminal capability name

       touchoverlap(win1,win2)
                           mark overlap of win1 on win2 as changed

   Use of curscr
       The  special  window curscr can be used in only a few routines.  If the
       window argument to clearok() is curscr, the  next  call  to  wrefresh()
       with  any window will cause the screen to be cleared and repainted from
       scratch.  If the window argument to wrefresh() is curscr, the screen is
       immediately  cleared and repainted from scratch.  This is how most pro-
       grams would implement a "repaint-screen" routine.   The  source  window
       argument to overlay(), overwrite(), and copywin may be curscr, in which
       case the current contents  of  the  virtual  terminal  screen  will  be
       accessed.

   Obsolete Calls
       Various  routines  are  provided  to maintain compatibility in programs
       written for older versions of the curses library.  These  routines  are
       all emulated as indicated below.

       crmode()            Replaced by cbreak().

       gettmode()          A no-op.

       nocrmode()          Replaced by nocbreak().

SYSTEM V ROUTINES
       The above routines are available as described except for flusok(), get-
       cap() and touchoverlap() which are not available.

       In addition, the following routines are available:

   Overall Screen Manipulation
       isendwin()          Returns TRUE if endwin() has  been  called  without
                           any subsequent calls to wrefresh().

       SCREEN *newterm(type, outfd, infd)
                           A  program  that  outputs to more than one terminal
                           must use newterm() for  each  terminal  instead  of
                           initscr().   A  program that wants an indication of
                           error conditions, so that it may continue to run in
                           a line-oriented mode if the terminal cannot support
                           a screen-oriented program, must also use this  rou-
                           tine.   newterm()  should  be  called once for each
                           terminal.  It returns a variable  of  type  SCREEN*
                           that  should be saved as a reference to that termi-
                           nal.  The arguments are the type of the terminal to
                           be  used in place of the environment variable TERM;
                           outfd, a stdio(3V) file pointer for output  to  the
                           terminal;  and infd, another file pointer for input
                           from the terminal.  When it is  done  running,  the
                           program  must  also call endwin() for each terminal
                           being used.  If newterm() is called more than  once
                           for  the same terminal, the first terminal referred
                           to must be the  last  one  for  which  endwin()  is
                           called.

       SCREEN *set_term (new)
                           This  routine  is  used to switch between different
                           terminals.  The screen reference  new  becomes  the
                           new  current  terminal.  A pointer to the screen of
                           the previous terminal is returned by  the  routine.
                           This  is  the  only routine that manipulates SCREEN
                           pointers; all other routines affect only  the  cur-
                           rent terminal.

   Window and Pad Manipulation
       wnoutrefresh (win)

       doupdate()          These  two  routines  allow multiple updates to the
                           physical terminal screen with more efficiency  than
                           wrefresh()  alone.   How  this  is  accomplished is
                           described in the next paragraph.
                           curses keeps two data structures  representing  the
                           terminal   screen:   a  physical  terminal  screen,
                           describing what is actually on the  screen,  and  a
                           virtual  terminal  screen, describing what the pro-
                           grammer wants to have on  the  screen.   wrefresh()
                           works by first calling wnoutrefresh(), which copies
                           the named window to the virtual screen, and then by
                           calling  doupdate(),  which  compares  the  virtual
                           screen to the physical screen and does  the  actual
                           update.  If the programmer wishes to output several
                           windows at once, a series of  calls  to  wrefresh()
                           will  result in alternating calls to wnoutrefresh()
                           and doupdate(), causing several bursts of output to
                           the  screen.   By  first calling wnoutrefresh() for
                           each window, it is then possible to call doupdate()
                           once,  resulting  in only one burst of output, with
                           probably fewer  total  characters  transmitted  and
                           certainly less processor time used.

       WINDOW *newpad (nlines, ncols)
                           Create  and  return  a  pointer  to  a new pad data
                           structure with the given number of lines (or rows),
                           nlines, and columns, ncols.  A pad is a window that
                           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, and only a part of the window will be on
                           the screen at one  time.   Automatic  refreshes  of
                           pads  (for  example,  from  scrolling or echoing of
                           input) do not occur.  It is not legal to call  wre-
                           fresh()  with  a  pad  as an argument; the routines
                           prefresh()  or  pnoutrefresh()  should  be   called
                           instead.   Note:  these routines require additional
                           parameters to specify the part of  the  pad  to  be
                           displayed and the location on the screen to be used
                           for display.

       WINDOW *subpad (orig, nlines, ncols, begin_y, begin_x)
                           Create and return a pointer to a subwindow within a
                           pad  with  the  given  number  of  lines (or rows),
                           nlines, and columns, ncols.  Unlike subwin(), which
                           uses  screen coordinates, the window is at position
                           (begin_y, begin_x) on the pad.  The window is  made
                           in  the  middle of the window orig, so that changes
                           made to one window will affect both windows.   When
                           using  this  routine, often it will be necessary to
                           call touchwin() or touchline() on orig before call-
                           ing prefresh().

       prefresh (pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol)


              pnoutrefresh
                           (pad,  pminrow, pmincol, sminrow, smincol, smaxrow,
                           smaxcol)

       These routines are analogous to
                           wrefresh() and  wnoutrefresh()  except  that  pads,
                           instead  of  windows, are involved.  The additional
                           parameters are needed to indicate what part of  the
                           pad  and  screen are involved.  pminrow and pmincol
                           specify the upper left corner, in the pad,  of  the
                           rectangle   to  be  displayed.   sminrow,  smincol,
                           smaxrow, and smaxcol  specify  the  edges,  on  the
                           screen,  of  the rectangle to be displayed in.  The
                           lower right corner in the pad of the  rectangle  to
                           be  displayed is calculated from the screen coordi-
                           nates, since the rectangles must be the same  size.
                           Both  rectangles  must be entirely contained within
                           their respective structures.   Negative  values  of
                           pminrow,  pmincol,  sminrow, or smincol are treated
                           as if they were zero.

   Output
       These routines are used to "draw" text on windows.

       echochar (ch)

       wechochar (win, ch)

       pechochar (pad, ch) These routines are  functionally  equivalent  to  a
                           call to addch (ch) followed by a call to refresh(),
                           a call to waddch (win, ch) followed by  a  call  to
                           wrefresh  (win), or a call to waddch (pad, ch) fol-
                           lowed by a call to prefresh (pad).   The  knowledge
                           that  only  a  single  character is being output is
                           taken into consideration and, for non-control char-
                           acters, a considerable performance gain can be seen
                           by using these routines instead  of  their  equiva-
                           lents.   In the case of pechochar(), the last loca-
                           tion of the pad on the screen  is  reused  for  the
                           arguments to prefresh().

                           Note:  ch is actually of type chtype, not a charac-
                           ter.

                           Note: echochar() is a macro.

       attroff (attrs)

       wattroff (win, attrs)

       attron (attrs)

       wattron (win, attrs)

       attrset (attrs)

       wattrset (win, attrs)

       beep()

       flash()             These routines are  used  to  signal  the  terminal
                           user.   beep()  will sound the audible alarm on the
                           terminal, if possible, and if not, will  flash  the
                           screen   (visible   bell),  if  that  is  possible.
                           flash() will flash the screen, and if that  is  not
                           possible,  will  sound the audible signal.  If nei-
                           ther  signal  is  possible,  nothing  will  happen.
                           Nearly  all  terminals have an audible signal (bell
                           or beep) but only some can flash the screen.

       delay_output (ms)   Insert a ms millisecond pause in the output.  It is
                           not  recommended  that  this routine be used exten-
                           sively, because padding characters are used  rather
                           than a processor pause.

       getbegyx (win, y, x)

       getmaxyx (win, y, x)
                           Like  getyx(),  these  routines  store  the current
                           beginning coordinates and  size  of  the  specified
                           window.

                           Note: getbegyx() and getmaxyx() are macros.

       copywin  (srcwin,  dstwin, sminrow, smincol, dminrow, dmincol, dmaxrow,
                           dmaxcol, overlay)
                           This routine provides a finer grain of control over
                           the  overlay()  and  overwrite() routines.  Like in
                           the prefresh() routine, a rectangle is specified in
                           the  destination  window,  (dminrow,  dmincol)  and
                           (dmaxrow, dmaxcol), and the upper-left-corner coor-
                           dinates  of  the source window, (sminrow, smincol).
                           If the argument overlay is true,  then  copying  is
                           non-destructive, as in overlay().

       vwprintw (win, fmt, varglist)
                           This  routine  corresponds to vprintf(3V).  It per-
                           forms a wprintw() using a variable  argument  list.
                           The  third  argument  is  a va_list, a pointer to a
                           list of arguments, as defined in <&lt;varargs.h>&gt;.   See
                           the  vprintf(3V)  and varargs(3) manual pages for a
                           detailed description on how to use  variable  argu-
                           ment lists.

   Input
       flushinp()          Throws  away  any  typeahead that has been typed by
                           the user and has not yet been read by the program.

       ungetch (c)         Place c back onto the input queue to be returned by
                           the next call to wgetch().

       vwscanw (win, fmt, ap)
                           This routine is similar to vwprintw() above in that
                           performs a wscanw() using a variable argument list.
                           The  third  argument  is  a va_list, a pointer to a
                           list of arguments, as defined in <&lt;varargs.h>&gt;.   See
                           the  vprintf(3V)  and varargs(3) manual pages for a
                           detailed description on how to use  variable  argu-
                           ment lists.

   Output Options Setting
       These  routines  set  options within curses that deal with output.  All
       options are initially FALSE, unless otherwise stated.  It is not neces-
       sary to turn these options off before calling endwin().

       setscrreg (top, bot)

       wsetscrreg (win, top, bot)
                           These  routines  allow  the  user to set a software
                           scrolling region in a window.  top and bot are  the
                           line  numbers  of  the top and bottom margin of the
                           scrolling region.  Line 0 is the top  line  of  the
                           window.  If this option and scrollok() are enabled,
                           an attempt to move off the bottom margin line  will
                           cause  all  lines in the scrolling region to scroll
                           up one line.  Note: this has nothing to do with use
                           of  a  physical  scrolling region capability in the
                           terminal, like that in the  DEC  VT100.   Only  the
                           text  of  the  window  is  scrolled;  if idlok() is
                           enabled and the terminal  has  either  a  scrolling
                           region  or  "insert/delete-line"  capability,  they
                           will probably be used by the output routines.

                           Note: setscrreg() and wsetscrreg() are macros.

   Input Options Setting
       These routines set options within curses that  deal  with  input.   The
       options  involve using ioctl(2) and therefore interact with curses rou-
       tines.  It is not necessary to turn these options  off  before  calling
       endwin().

       For more information on these options, refer to

       halfdelay (tenths)  Half-delay  mode  is similar to CBREAK mode in that
                           characters typed by the user are immediately avail-
                           able  to  the program.  However, after blocking for
                           tenths tenths of seconds, ERR will be  returned  if
                           nothing  has  been  typed.  tenths must be a number
                           between 1 and 255.  Use nocbreak() to  leave  half-
                           delay mode.

       intrflush (win, bf) If this option is enabled, when an interrupt key is
                           pressed on the keyboard  (interrupt,  break,  quit)
                           all output in the tty driver queue will be flushed,
                           giving the effect of faster response to the  inter-
                           rupt,  but causing curses to have the wrong idea of
                           what is on the screen.  Disabling the  option  pre-
                           vents  the  flush.   The  default for the option is
                           inherited from the tty driver settings.  The window
                           argument is ignored.

       keypad (win, bf)    This option enables the keypad of the user's termi-
                           nal.  If enabled, the user can press a function key
                           (such  as  an arrow key) and wgetch() will return a
                           single value representing the function key,  as  in
                           KEY_LEFT.  If disabled, curses will not treat func-
                           tion keys specially and the program would  have  to
                           interpret the escape sequences itself.  If the key-
                           pad in the terminal  can  be  turned  on  (made  to
                           transmit)  and  off (made to work locally), turning
                           on this option will cause the terminal keypad to be
                           turned on when wgetch() is called.

       meta (win, bf)      If  enabled,  characters  returned  by wgetch() are
                           transmitted with all 8 bits, instead  of  with  the
                           highest  bit stripped.  In order for meta() to work
                           correctly, the km (has_meta_key) capability has  to
                           be specified in the terminal's terminfo(5V) entry.

       nodelay (win, bf)   This  option  causes  wgetch() to be a non-blocking
                           call.  If no input is ready, wgetch()  will  return
                           ERR.   If  disabled, wgetch() will hang until a key
                           is pressed.

       notimeout (win, bf) While  interpreting  an  input   escape   sequence,
                           wgetch()  will  set  a  timer while waiting for the
                           next  character.   If  notimeout  (win,  TRUE)   is
                           called,  then  wgetch()  will not set a timer.  The
                           purpose of the timeout is to differentiate  between
                           sequences  received  from  a function key and those
                           typed by a user.

       typeahead (fildes)  curses does "line-breakout optimization" by looking
                           for   typeahead  periodically  while  updating  the
                           screen.  If input is found, and it is coming from a
                           tty,  the  current  update  will be postponed until
                           refresh() or  doupdate()  is  called  again.   This
                           allows   faster   response  to  commands  typed  in
                           advance.  Normally, the  file  descriptor  for  the
                           input FILE pointer passed to newterm(), or stdin in
                           the case that initscr() was used, will be  used  to
                           do  this  typeahead checking.  The typeahead() rou-
                           tine specifies that the file descriptor  fildes  is
                           to  be  used  to  check  for typeahead instead.  If
                           fildes is -1, then no typeahead  checking  will  be
                           done.

                           Note:  fildes is a file descriptor, not a <&lt;stdio.h>&gt;
                           FILE pointer.

   Environment Queries
       has_ic()            True if the terminal has insert- and delete-charac-
                           ter capabilities.

       has_il()            True  if  the  terminal has insert- and delete-line
                           capabilities, or can simulate them using  scrolling
                           regions.   This might be used to check to see if it
                           would be appropriate to turn on physical  scrolling
                           using scrollok().

   Soft Labels
       If  desired, curses will manipulate the set of soft function-key labels
       that exist on many terminals.  For those terminals  that  do  not  have
       soft  labels,  if  you want to simulate them, curses will take over the
       bottom line of stdscr, reducing the size of  stdscr  and  the  variable
       LINES.  curses standardizes on 8 labels of 8 characters each.

       slk_init (labfmt)   In  order  to use soft labels, this routine must be
                           called before initscr() or newterm() is called.  If
                           initscr() winds up using a line from stdscr to emu-
                           late the soft labels, then  labfmt  determines  how
                           the  labels  are  arranged  on the screen.  Setting
                           labfmt to 0 indicates that the  labels  are  to  be
                           arranged  in  a 3-2-3 arrangement; 1 asks for a 4-4
                           arrangement.

       slk_set (labnum, label, labfmt)
                           labnum is the label number, from 1 to 8.  label  is
                           the  string to be put on the label, up to 8 charac-
                           ters in length.  A null string or  a  NULL  pointer
                           will  put  up a blank label.  labfmt is one of 0, 1
                           or 2, to indicate whether the label is to be  left-
                           justified,  centered, or right-justified within the
                           label.

       slk_refresh()

       slk_noutrefresh()   These routines  correspond  to  the  routines  wre-
                           fresh()   and  wnoutrefresh().   Most  applications
                           would use slk_noutrefresh()  because  a  wrefresh()
                           will most likely soon follow.

       char *slk_label (labnum)
                           The  current  label  for  label number labnum, with
                           leading and trailing blanks stripped, is returned.

       slk_clear()         The soft labels are cleared from the screen.

       slk_restore()       The soft labels are restored to the screen after  a
                           slk_clear().

       slk_touch()         All  of the soft labels are forced to be output the
                           next time a slk_noutrefresh() is performed.

   Low-Level curses Access
       The following routines give low-level access to  various  curses  func-
       tionality.   These  routines  typically would be used inside of library
       routines.

       def_prog_mode()

       def_shell_mode()    Save the current terminal modes  as  the  "program"
                           (in  curses)  or  "shell" (not in curses) state for
                           use by the reset_prog_mode() and reset_shell_mode()
                           routines.  This is done automatically by initscr().

       reset_prog_mode()

       reset_shell_mode()  Restore  the  terminal  to "program" (in curses) or
                           "shell" (out of  curses)  state.   These  are  done
                           automatically  by  endwin() and doupdate() after an
                           endwin(), so they normally would not be called.

       getsyx (y, x)       The current coordinates of the virtual screen  cur-
                           sor  are  returned  in  y and x.  Like getyx(), the
                           variables y and x do not take an &&amp; before them.  If
                           leaveok()  is  currently  TRUE, then -1, -1 will be
                           returned.  If lines may have been removed from  the
                           top of the screen using ripoffline() and the values
                           are to be used beyond just passing them on to  set-
                           syx(),  the value y+stdscr->&gt;_yoffset should be used
                           for those other uses.

                           Note: getsyx() is a macro.

       setsyx (y, x)       The virtual screen cursor is set to y, x.  If y and
                           x are both -1, then leaveok() will be set.  The two
                           routines getsyx() and setsyx() are designed  to  be
                           used  by  a library routine that manipulates curses
                           windows but does not want to mess  up  the  current
                           position of the program's cursor.  The library rou-
                           tine would call getsyx() at the beginning,  do  its
                           manipulation  of  its  own  windows,  do a wnoutre-
                           fresh() on its windows,  call  setsyx(),  and  then
                           call doupdate().

       ripoffline (line, init)
                           This  routine  provides access to the same facility
                           that slk_init() uses to  reduce  the  size  of  the
                           screen.    ripoffline()   must   be  called  before
                           initscr() or newterm() is called.  If line is posi-
                           tive,  a  line will be removed from the top of std-
                           scr; if negative, a line will be removed  from  the
                           bottom.   When  this  is done inside initscr(), the
                           routine init is called with two arguments: a window
                           pointer  to  the  1-line window that has been allo-
                           cated and an integer with the number of columns  in
                           the  window.   Inside  this initialization routine,
                           the integer variables LINES and  COLS  (defined  in
                           <&lt;curses.h>&gt;)  are  not guaranteed to be accurate and
                           wrefresh() or doupdate() must not be called.  It is
                           allowable  to  call  wnoutrefresh() during the ini-
                           tialization routine.

                           ripoffline() can be called up to five times  before
                           calling initscr() or newterm().

       scr_dump (filename) The  current  contents  of  the  virtual screen are
                           written to the file filename.

       scr_restore (filename)
                           The virtual screen is set to the contents of  file-
                           name,   which   must   have   been   written  using
                           scr_dump().   The  next  call  to  doupdate()  will
                           restore  the  screen  to what it looked like in the
                           dump file.

       scr_init (filename) The contents of filename are read in  and  used  to
                           initialize  the  curses  data structures about what
                           the terminal currently has on its screen.   If  the
                           data  is  determined  to be valid, curses will base
                           its next update of the screen on  this  information
                           rather  than  clearing the screen and starting from
                           scratch.  scr_init() would be used after  initscr()
                           or  a  system(3)  call  to  share  the  screen with
                           another process that has done  a  scr_dump()  after
                           its  endwin()  call.   The  data  will  be declared
                           invalid if the time-stamp of the tty is old or  the
                           terminfo(5V) capability nrrmc is true.

       curs_set (visibility)
                           The  cursor  is  set  to invisible, normal, or very
                           visible for visibility equal to 0, 1 or 2.

       draino (ms)         Wait until the output has drained  enough  that  it
                           will  only  take ms more milliseconds to drain com-
                           pletely.

       garbagedlines (win, begline, numlines)
                           This routine indicates to curses that a screen line
                           is garbaged and should be thrown away before having
                           anything written over the top of it.  It  could  be
                           used  for programs such as editors that want a com-
                           mand to redraw just a single line.  Such a  command
                           could  be used in cases where there is a noisy com-
                           munications line and redrawing  the  entire  screen
                           would  be subject to even more communication noise.
                           Just redrawing the single line gives some semblance
                           of  hope  that  it  would show up unblemished.  The
                           current location of the window is used to determine
                           which lines are to be redrawn.

       napms (ms)          Sleep for ms milliseconds.

   Terminfo-Level Manipulations
       These  low-level  routines must be called by programs that need to deal
       directly with the terminfo(5V)  database  to  handle  certain  terminal
       capabilities,  such  as programming function keys.  For all other func-
       tionality, curses routines are more suitable and their  use  is  recom-
       mended.

       Initially, setupterm() should be called.  Note: setupterm() is automat-
       ically called by initscr() and newterm().  This will define the set  of
       terminal-dependent variables defined in the terminfo(5V) database.  The
       terminfo(5V) variables lines and columns (see  terminfo(5V))  are  ini-
       tialized  by setupterm() as follows: if the environment variables LINES
       and COLUMNS exist, their values are used.   If  the  above  environment
       variables  do  not  exist,  and the window sizes in rows and columns as
       returned by the TIOCGWINSZ ioctl are non-zero, those  sizes  are  used.
       Otherwise,  the  values  for  lines  and  columns specified in the ter-
       minfo(5V) database are used.

       The header files <curses.h> and <term.h> should be  included,  in  this
       order,  to  get  the definitions for these strings, numbers, and flags.
       Parameterized strings should be passed through tparm()  to  instantiate
       them.  All terminfo(5V) strings (including the output of tparm() should
       be printed with tputs() or putp().  Before exiting,  reset_shell_mode()
       should  be  called  to restore the tty modes.  Programs that use cursor
       addressing should output enter_ca_mode upon startup and  should  output
       exit_ca_mode  before  exiting  (see  terminfo(5V)).   Programs desiring
       shell escapes should call reset_shell_mode()  and  output  exit_ca_mode
       before  the  shell  is  called and should output enter_ca_mode and call
       reset_prog_mode() after returning from the shell.  Note: this  is  dif-
       ferent from the curses routines (see endwin()).

       setupterm (term, fildes, errret)
                           Reads  in  the  terminfo(5V) database, initializing
                           the terminfo(5V) structures, but does  not  set  up
                           the   output   virtualization  structures  used  by
                           curses.  The terminal  type  is  in  the  character
                           string term; if term is NULL, the environment vari-
                           able TERM will be used.  All output is to the  file
                           descriptor  fildes.   If  errret  is not NULL, then
                           setupterm() will return OK or ERR and store a  sta-
                           tus  value  in the integer pointed to by errret.  A
                           status of 1 in errret is normal, 0 means  that  the
                           terminal  could not be found, and -1 means that the
                           terminfo(5V)  database  could  not  be  found.   If
                           errret  is  NULL,  setupterm()  will print an error
                           message upon finding an error and exit.  Thus,  the
                           simplest  call  is  `setupterm  ((char *)0, 1, (int
                           *)0)', which uses all the defaults.

                           The terminfo(5V) boolean, numeric and string  vari-
                           ables  are  stored in a structure of type TERMINAL.
                           After setupterm() returns successfully,  the  vari-
                           able  cur_term  (of type TERMINAL *) is initialized
                           with all of the information that  the  terminfo(5V)
                           boolean,  numeric  and  string  variables refer to.
                           The pointer may be saved before calling setupterm()
                           again.   Further calls to setupterm() will allocate
                           new space rather than reuse the space pointed to by
                           cur_term.

       set_curterm (nterm) nterm  is  of type TERMINAL * .  set_curterm() sets
                           the variable cur_term to nterm, and  makes  all  of
                           the  terminfo(5V) boolean, numeric and string vari-
                           ables use the values from nterm.

       del_curterm (oterm) oterm is of type TERMINAL *.   del_curterm()  frees
                           the  space  pointed to by oterm and makes it avail-
                           able for further use.  If  oterm  is  the  same  as
                           cur_term,  then  references  to  any  of  the  ter-
                           minfo(5V) boolean,  numeric  and  string  variables
                           thereafter  may  refer  to invalid memory locations
                           until another setupterm() has been called.

       restartterm (term, fildes, errret)
                           Like setupterm() after a memory restore.

       char *tparm (str, p1, p2, ..., p9)
                           Instantiate  the  string  str  with  parms  pi.   A
                           pointer  is  returned to the result of str with the
                           parameters applied.

       tputs (str, count, putc)
                           Apply padding to the string str and output it.  str
                           must  be  a  terminfo(5V)  string  variable  or the
                           return value from tparm(), tgetstr(), tigetstr() or
                           tgoto().  count is the number of lines affected, or
                           1 if not applicable.  putchar() is a  putc(3s)-like
                           routine  to which the characters are passed, one at
                           a time.

       putp (str)          A routine that calls tputs() (str, 1, putc(3s).

       vidputs (attrs, putc)
                           Output a string that puts the terminal in the video
                           attribute  mode  attrs, which is any combination of
                           the attributes listed below.   The  characters  are
                           passed to the putc(3s)-like routine putc(3s).

       vidattr (attrs)     Like  vidputs(),  except  that  it  outputs through
                           putc(3s).

       tigetflag (capname) The value -1 is returned if capname is not a  bool-
                           ean capability.

       tigetnum (capname)  The  value  -2  is  returned  if  capname  is not a
                           numeric capability.

       tigetstr (capname)  The value (char *) -1 is returned if capname is not
                           a string capability.

   Termcap Emulation
       These  routines  are included as a conversion aid for programs that use
       the termcap(3X) library.  Their parameters are the same  and  the  rou-
       tines are emulated using the terminfo(5V) database.

       tgetent (bp, name)  Look  up  termcap  entry  for  name.  The emulation
                           ignores the buffer pointer bp.

       tgetflag (codename) Get the boolean entry for codename.

       tgetnum (codes)     Get numeric entry for codename.

       char *tgetstr (codename, area)
                           Return the string entry for codename.  If  area  is
                           not  NULL, then also store it in the buffer pointed
                           to by area and advance  area.   tputs()  should  be
                           used to output the returned string.

       char *tgoto (cap, col, row)
                           Instantiate  the parameters into the given capabil-
                           ity.  The output from this routine is to be  passed
                           to tputs().

       tputs (str, affcnt, putc)
                           See  tputs()  above, under Terminfo-Level Manipula-
                           tions.

   Miscellaneous
       char *keyname (c)   A character string corresponding to the  key  c  is
                           returned.

       filter()            This routine is one of the few that is to be called
                           before  initscr()  or  newterm()  is  called.    It
                           arranges things so that curses thinks that there is
                           a 1-line screen.  curses will not use any  terminal
                           capabilities  that  assume that they know what line
                           on the screen the cursor is on.

   Use of curscr
       The special window curscr can be used in only a few routines.   If  the
       window  argument  to  clearok()  is curscr, the next call to wrefresh()
       with any window will cause the screen to be cleared and repainted  from
       scratch.  If the window argument to wrefresh() is curscr, the screen is
       immediately cleared and repainted from scratch.  This is how most  pro-
       grams  would  implement  a "repaint-screen" routine.  The source window
       argument to overlay(), overwrite(), and copywin may be curscr, in which
       case  the  current  contents  of  the  virtual  terminal screen will be
       accessed.

   Obsolete Calls
       Various routines are provided to  maintain  compatibility  in  programs
       written  for  older versions of the curses library.  These routines are
       all emulated as indicated below.

       crmode()            Replaced by cbreak().

       fixterm()           Replaced by reset_prog_mode().

       nocrmode()          Replaced by nocbreak().

       resetterm()         Replaced by reset_shell_mode().

       saveterm()          Replaced by def_prog_mode().

       setterm()           Replaced by setupterm().

SYSTEM V ATTRIBUTES
       The following video attributes, defined in <curses.h>, can be passed to
       the  routines  attron(),  attroff(),  and  attrset(), or OR'ed with the
       characters passed to addch().

       ; l l l .  A_STANDOUT     Terminal's best  highlighting  mode  A_UNDER-
       LINE    Underlining    A_REVERSE Reverse    video    A_BLINK   Blinking
       A_DIM     Half    bright     A_BOLD    Extra     bright     or     bold
       A_ALTCHARSET   Alternate character set

       A_CHARTEXT     Bit-mask  to  extract  character (described under winch)
       A_ATTRIBUTES   Bit-mask to extract attributes (described  under  winch)
       A_NORMAL  Bit  mask  to  reset  all  attributes  off      (for example:
       `attrset (A_NORMAL)'

SYSTEM V FUNCTION KEYS
       The following function keys, defined in <curses.h>, might  be  returned
       by getch() if keypad() has been enabled.  Note: not all of these may be
       supported on a particular terminal if the terminal does not transmit  a
       unique  code  when  the key is pressed or the definition for the key is
       not present in the terminfo(5V) database.


       center; l l l .  Name Value     Key name

       KEY_BREAK 0401 break key  (unreliable)  KEY_DOWN  0402 The  four  arrow
       keys     ...     KEY_UP    0403    KEY_LEFT  0404    KEY_RIGHT 0405 ...
       KEY_HOME  0406 Home          key          (upward+left           arrow)
       KEY_BACKSPACE  0407 backspace    (unreliable)   KEY_F0    0410 Function
       keys.  Space for 64 keys is reserved.  KEY_F(n)  (KEY_F0+(n))   Formula
       for   fn.    KEY_DL    0510 Delete   line   KEY_IL    0511 Insert  line
       KEY_DC    0512 Delete character  KEY_IC    0513 Insert  char  or  enter
       insert  mode  KEY_EIC   0514 Exit insert char mode KEY_CLEAR 0515 Clear
       screen KEY_EOS   0516 Clear to end of  screen  KEY_EOL   0517 Clear  to
       end  of line KEY_SF    0520 Scroll 1 line forward KEY_SR    0521 Scroll
       1 line backwards (reverse) KEY_NPAGE 0522 Next page KEY_PPAGE 0523 Pre-
       vious    page    KEY_STAB  0524 Set    TAB   KEY_CTAB  0525 Clear   TAB
       KEY_CATAB 0526 Clear all TAB characters  KEY_ENTER 0527 Enter  or  send
       KEY_SRESET     0530 soft  (partial)  reset KEY_RESET 0531 reset or hard
       reset KEY_PRINT 0532 print or copy KEY_LL    0533 home down  or  bottom
       (lower  left)            keypad  is  arranged like this:             A1
       up     A3             left  B2     right              C1     down    C3
       KEY_A1    0534 Upper  left of keypad KEY_A3    0535 Upper right of key-
       pad KEY_B2    0536 Center of keypad KEY_C1    0537 Lower left of keypad
       KEY_C3    0540 Lower   right  of  keypad  KEY_BTAB  0541 Back  TAB  key
       KEY_BEG   0542 beg(inning)    key    KEY_CANCEL     0543 cancel     key
       KEY_CLOSE 0544 close    key   KEY_COMMAND    0545 cmd   (command)   key
       KEY_COPY  0546 copy      key       KEY_CREATE     0547 create       key
       KEY_END   0550 end  key KEY_EXIT  0551 exit key KEY_FIND  0552 find key
       KEY_HELP  0553 help    key     KEY_MARK  0554 mark     key     KEY_MES-
       SAGE    0555 message  key  KEY_MOVE  0556 move  key KEY_NEXT  0557 next
       object  key  KEY_OPEN  0560 open  key  KEY_OPTIONS    0561 options  key
       KEY_PREVIOUS   0562 previous   object   key   KEY_REDO  0563 redo   key
       KEY_REFERENCE  0564 ref(erence)  key  KEY_REFRESH    0565 refresh   key
       KEY_REPLACE    0566 replace    key    KEY_RESTART    0567 restart   key
       KEY_RESUME     0570 resume      key       KEY_SAVE  0571 save       key
       KEY_SBEG  0572 shifted beginning key KEY_SCANCEL    0573 shifted cancel
       key KEY_SCOMMAND   0574 shifted command key KEY_SCOPY 0575 shifted copy
       key   KEY_SCREATE    0576 shifted   create  key  KEY_SDC   0577 shifted
       delete   char    key    KEY_SDL   0600 shifted    delete    line    key
       KEY_SELECT     0601 select    key    KEY_SEND  0602 shifted   end   key
       KEY_SEOL  0603 shifted clear line key KEY_SEXIT 0604 shifted  exit  key
       KEY_SFIND 0605 shifted   find   key   KEY_SHELP 0606 shifted  help  key
       KEY_SHOME 0607 shifted  home  key  KEY_SIC   0610 shifted   input   key
       KEY_SLEFT 0611 shifted  left arrow key KEY_SMESSAGE   0612 shifted mes-
       sage key KEY_SMOVE 0613 shifted move  key  KEY_SNEXT 0614 shifted  next
       key KEY_SOPTIONS   0615 shifted options key KEY_SPREVIOUS  0616 shifted
       prev key KEY_SPRINT     0617 shifted print  key  KEY_SREDO 0620 shifted
       redo       key       KEY_SREPLACE   0621 shifted       replace      key
       KEY_SRIGHT     0622 shifted  right  arrow   KEY_SRSUME     0623 shifted
       resume  key KEY_SSAVE 0624 shifted save key KEY_SSUSPEND   0625 shifted
       suspend key KEY_SUNDO 0626 shifted undo key KEY_SUSPEND    0627 suspend
       key KEY_UNDO  0630 undo key

LINE GRAPHICS
       The  following  variables may be used to add line-drawing characters to
       the screen with waddce.  When defined for the  terminal,  the  variable
       will have the A_ALTCHARSET bit turned on.  Otherwise, the default char-
       acter listed below will be stored in the variable.  The names were cho-
       sen to be consistent with the DEC VT100 nomenclature.

       l c l .  Name Default   Glyph Description

       ACS_ULCORNER   +    upper  left  corner  ACS_LLCORNER   +    lower left
       corner ACS_URCORNER   +    upper right corner ACS_LRCORNER   +    lower
       right  corner ACS_RTEE  +    right tee (-|) ACS_LTEE  +    left tee (-)
       ACS_BTEE  +    bottom    tee    (|)    ACS_TTEE  +    top    tee    (|)
       ACS_HLINE -    horizontal     line     ACS_VLINE |    vertical     line
       ACS_PLUS  +    plus ACS_S1    -    scan line 1 ACS_S9    _    scan line
       9  ACS_DIAMOND    +    diamond ACS_CKBOARD    :    checker board (stip-
       ple) ACS_DEGREE     '    degree  symbol  ACS_PLMINUS    #    plus/minus
       ACS_BULLET     o    bullet   ACS_LARROW     <    arrow   pointing  left
       ACS_RARROW     >    arrow  pointing   right   ACS_DARROW     v    arrow
       pointing      down      ACS_UARROW     ^    arrow      pointing      up
       ACS_BOARD #    board  of  squares  ACS_LANTERN    #    lantern   symbol
       ACS_BLOCK #    solid square block

RETURN VALUES
       Unless  otherwise noted in the preceding routine descriptions, all rou-
       tines return:

       OK     on success.

       ERR    on failure.

SYSTEM V RETURN VALUES
       All macros return the value of their  w  version,  except  setscrreg(),
       wsetscrreg(), getsyx(), getyx(), getbegy(), getmaxyx(), which return no
       useful value.

       Routines that return pointers always return (type *) NULL on failure.

FILES
       .login

       .profile

SYSTEM V FILES
       /usr/share/lib/terminfo

SEE ALSO
       cc(1V), ld(1), ioctl(2), getenv(3V),  plot(3X),  printf(3V),  putc(3S),
       scanf(3V),  stdio(3V),  system(3),  varargs(3), vprintf(3V), termio(4),
       tty(4), term(5V), termcap(5), terminfo(5V), tic(8V)

SYSTEM V WARNINGS
       The plotting library plot(3X) and the curses  library  curses(3V)  both
       use  the names erase() and move().  The curses versions are macros.  If
       you need both libraries, put the plot(3X) code in  a  different  source
       file  than the curses(3V) code, and/or `#undef move' and `#undef erase'
       in the plot(3X) code.

       Between the time a call to initscr() and endwin() has been issued,  use
       only the routines in the curses library to generate output.  Using sys-
       tem calls or the "standard I/O package" (see stdio(3V)) for output dur-
       ing that time can cause unpredictable results.



4th Berkeley Distribution       21 January 1990                     CURSES(3V)