


      CURSES(3X)                  (UNIX 5.2)                 CURSES(3X)



      NAME
           curses - CRT screen handling and optimization package

      SYNTAX
           #include <curses.h>
           cc [ flags ] files -lcurses [ libraries ]

      DESCRIPTION
           These routines give the user a method of updating screens
           with reasonable optimization.  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.
           To get character-at-a-time input without echoing, (most
           interactive, screen oriented-programs want this) after
           calling initscr() you should call ``nonl(); cbreak();
           noecho();''

           The full curses interface permits manipulation of data
           structures called windows which can be thought of as two
           dimensional arrays of characters representing all or part of
           a CRT screen.  A default window called stdscr is supplied,
           and others can be created with newwin.  Windows are referred
           to by variables declared ``WINDOW *'', the type WINDOW is
           defined in curses.h to be a C structure.  These data
           structures are manipulated with functions described below,
           among which the most basic are move, and addch.  (More
           general versions of these functions are included with names
           beginning with `w', allowing you to specify a window.  The
           routines not beginning with `w' affect stdscr.) Then
           refresh() is called, telling the routines to make the users
           CRT screen look like stdscr.

           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
           standard place is /usr/lib/terminfo, and TERM is set to
           ``vt100'', then normally the compiled file is found in
           /usr/lib/terminfo/v/vt100.  (The ``v'' is copied from the
           first letter of ``vt100'' to avoid creation of huge
           directories.) However, if TERMINFO is set to
           /usr/mark/myterms, curses will first check
           /usr/mark/myterms/v/vt100, and if that fails, will then
           check /usr/lib/terminfo/v/vt100.  This is useful for
           developing experimental definitions or when write permission
           in /usr/lib/terminfo is not available.

      SEE ALSO
           terminfo(4).

      FUNCTIONS
           Routines listed here may be called when using the full



      Page 1                                         (73 A2 02MTA REV1)






      CURSES(3X)                  (UNIX 5.2)                 CURSES(3X)



           curses.

           addch(ch)                add a character to stdscr
                                    (like putchar) (wraps to next
                                    line at end of line)
           addstr(str)              calls addch with each character in str
           attroff(attrs)           turn off attributes named
           attron(attrs)            turn on attributes named
           attrset(attrs)           set current attributes to attrs
           baudrate()               current terminal speed
           beep()                   sound beep on terminal
           box(win, vert, hor)      draw a box around edges of win
                                    vert and hor are chars to use for vert.
                                    and hor. edges of box
           clear()                  clear stdscr
           clearok(win, bf)         clear screen before next redraw of win
           clrtobot()               clear to bottom of stdscr
           clrtoeol()               clear to end of line on stdscr
           cbreak()                 set cbreak mode
           delay_output(ms)         insert ms millisecond pause in output
           delch()                  delete a character
           deleteln()               delete a line
           delwin(win)              delete win
           doupdate()               update screen from all wnooutrefresh
           echo()                   set echo mode
           endwin()                 end window modes
           erase()                  erase stdscr
           erasechar()              return user's erase character
           fixterm()                restore tty to "in curses" state
           flash()                  flash screen or beep
           flushinp()               throw away any typeahead
           getch()                  get a char from tty
           getstr(str)              get a string through stdscr
           gettmode()               establish current tty modes
           getyx(win, y, x)         get (y, x) co-ordinates
           has_ic()                 true if terminal can do insert character
           has_il()                 true if terminal can do insert line
           idlok(win, bf)           use terminal's insert/delete line if bf != 0
           inch()                   get char at current (y, x) co-ordinates
           initscr()                initialize screens
           insch(c)                 insert a char
           insertln()               insert a line
           intrflush(win, bf)       interrupts flush output if bf is TRUE
           keypad(win, bf)          enable keypad input
           killchar()               return current user's kill character
           leaveok(win, flag)       OK to leave cursor anywhere after refresh if
                                    flag!=0 for win, otherwise cursor must be left
                                    at current position.
           longname()               return verbose name of terminal
           meta(win, flag)          allow meta characters on input if flag != 0
           move(y, x)               move to (y, x) on stdscr
           mvaddch(y, x, ch)        move(y, x) then addch(ch)



      Page 2                                         (73 A2 02MTA REV1)






      CURSES(3X)                  (UNIX 5.2)                 CURSES(3X)



           mvaddstr(y, x, str)      similar...
           mvcur(oldrow, oldcol, newrow, newcol)
                                    low level cursor motion
           mvdelch(y, x)            like delch, but move(y, x) first
           mvgetch(y, x)            etc.
           mvgetstr(y, x)
           mvinch(y, x)
           mvinsch(y, x, c)
           mvprintw(y, x, fmt, args)
           mvscanw(y, x, fmt, args)
           mvwaddch(win, y, x, ch)
           mvwaddstr(win, y, x, str)
           mvwdelch(win, y, x)
           mvwgetch(win, y, x)
           mvwgetstr(win, y, x)
           mvwin(win, by, bx)
           mvwinch(win, y, x)
           mvwinsch(win, y, x, c)
           mvwprintw(win, y, x, fmt, args)
           mvwscanw(win, y, x, fmt, args)
           newpad(nlines, ncols)    create a new pad with given dimensions
           newterm(type, fd)        set up new terminal of given type to output on fd
           newwin(lines, cols, begin_y, begin_x)
                                    create a new window
           nl()                     set newline mapping
           nocbreak()               unset cbreak mode
           nodelay(win, bf)         enable nodelay input mode through getch
           noecho()                 unset echo mode
           nonl()                   unset newline mapping
           noraw()                  unset raw mode
           overlay(win1, win2)      overlay win1 on win2
           overwrite(win1, win2)    overwrite win1 on top of win2
           pnoutrefresh(pad, pminrow, pmincol, sminrow,
           smincol, smaxrow, smaxcol)
                                    like prefresh but with no output until doupdate called
           prefresh(pad, pminrow, pmincol, sminrow,
           smincol, smaxrow, smaxcol)
                                    refresh from pad starting with given upper left
                                    corner of pad with output to given
                                    portion of screen
           printw(fmt, arg1, arg2, ...)
                                    printf on stdscr
           raw()                    set raw mode
           refresh()                make current screen look like stdscr
           resetterm()              set tty modes to "out of curses" state
           resetty()                reset tty flags to stored value
           saveterm()               save current modes as "in curses" state
           savetty()                store current tty flags
           scanw(fmt, arg1, arg2, ...)
                                    scanf through stdscr
           scroll(win)              scroll win one line
           scrollok(win, flag)      allow terminal to scroll if flag != 0



      Page 3                                         (73 A2 02MTA REV1)






      CURSES(3X)                  (UNIX 5.2)                 CURSES(3X)



           set_term(new)            now talk to terminal new
           setscrreg(t, b)          set user scrolling region to lines t through b
           setterm(type)            establish terminal with given type
           setupterm(term, filenum, errret)
           standend()               clear standout mode attribute
           standout()               set standout mode attribute
           subwin(win, lines, cols, begin_y, begin_x)
                                    create a subwindow
           touchwin(win)            change all of win
           traceoff()               turn off debugging trace output
           traceon()                turn on debugging trace output
           typeahead(fd)            use file descriptor fd to check typeahead
           unctrl(ch)               printable version of ch
           waddch(win, ch)          add char to win
           waddstr(win, str)        add string to win
           wattroff(win, attrs)     turn off attrs in win
           wattron(win, attrs)      turn on attrs in win
           wattrset(win, attrs)     set attrs in win to attrs
           wclear(win)              clear win
           wclrtobot(win)           clear to bottom of win
           wclrtoeol(win)           clear to end of line on win
           wdelch(win, c)           delete char from win
           wdeleteln(win)           delete line from win
           werase(win)              erase win
           wgetch(win)              get a char through win
           wgetstr(win, str)        get a string through win
           winch(win)               get char at current (y, x) in win
           winsch(win, c)           insert char into win
           winsertln(win)           insert line into win
           wmove(win, y, x)         set current (y, x) co-ordinates on win
           wnoutrefresh(win)        refresh but no screen output
           wprintw(win, fmt, arg1, arg2, ...)
                                    printf on win
           wrefresh(win)            make screen look like win
           wscanw(win, fmt, arg1, arg2, ...)
                                    scanf through win
           wsetscrreg(win, t, b)    set scrolling region of win
           wstandend(win)           clear standout attribute in win
           wstandout(win)           set standout attribute in win

      TERMINFO LEVEL ROUTINES
           These routines should be called by programs wishing to deal
           directly with the terminfo database.  Due to the low level
           of this interface, it is discouraged.  Initially, setupterm
           should be called.  This will define the set of terminal
           dependent variables defined in terminfo(4).  The include
           files <curses.h> and <term.h> should be included to get the
           definitions for these strings, numbers, and flags.
           Parmeterized strings should be passed through tparm to
           instantiate them.  All terminfo strings (including the
           output of tparm) should be printed with tputs or putp .
           Before exiting, resetterm should be called to restore the



      Page 4                                         (73 A2 02MTA REV1)






      CURSES(3X)                  (UNIX 5.2)                 CURSES(3X)



           tty modes.  (Programs desiring shell escapes or suspending
           with control Z can call resetterm before the shell is called
           and fixterm after returning from the shell.)
           fixterm()                restore tty modes for terminfo use
                                    (called by setupterm)
           resetterm()              reset tty modes to state before program entry
           setupterm(term, fd, rc)  read in database.  Terminal type is the
                                    character string term, all output is to UNIX
                                    System file descriptor fd.  A status value is
                                    returned in the integer pointed to by rc: 1
                                    is normal.  The simplest call would be
                                    setupterm(0, 1, 0) which uses all defaults.
           tparm(str, p1, p2, ..., p9)
                                    instantiate string str with parms p9i8.
           tputs(str, affcnt, putc) apply padding info to string str.
                                    affcnt is the number of lines affected,
                                    or 1 if not applicable.  Putc is a
                                    putchar-like function to which the characters
                                    are passed, one at a time.
           putp(str)                handy function that calls tputs
                                    (str, 1, putchar)
           vidputs(attrs, putc)     output the string to put terminal in video
                                    attribute mode attrs, which is any
                                    combination of the attributes listed below.
                                    Chars are passed to putchar-like
                                    function putc.
           vidattr(attrs)           Like vidputs but outputs through
                                    putchar

      TERMCAP COMPATIBILITY ROUTINES
           These routines were included as a conversion aid for
           programs that use termcap.  Their parameters are the same as
           for termcap.  They are emulated using the terminfo database.
           They may go away at a later date.
           tgetent(bp, name)        look up termcap entry for name
           tgetflag(id)             get boolean entry for id
           tgetnum(id)              get numeric entry for id
           tgetstr(id, area)        get string entry for id
           tgoto(cap, col, row)     apply parms to given cap
           tputs(cap, affcnt, fn)   apply padding to cap calling fn as putchar

      ATTRIBUTES
           The following video attributes can be passed to the
           functions attron,attroff,attrset.
           A_STANDOUT     Terminal's best highlighting mode
           A_UNDERLINE    Underlining
           A_REVERSE      Reverse video
           A_BLINK        Blinking
           A_DIM          Half bright
           A_BOLD         Extra bright or bold
           A_BLANK        Blanking (invisible)
           A_PROTECT      Protected



      Page 5                                         (73 A2 02MTA REV1)






      CURSES(3X)                  (UNIX 5.2)                 CURSES(3X)



           A_ALTCHARSET   Alternate character set

      FUNCTION KEYS
           The following function keys might be returned by getch if
           keypad has been enabled.  Note that not all of these are
           currently supported, due to lack of definitions in terminfo
           or the terminal not transmitting a unique code when the key
           is pressed.
           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 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     Previous page
           KEY_STAB       0524     Set tab
           KEY_CTAB       0525     Clear tab
           KEY_CATAB      0526     Clear all tabs
           KEY_ENTER      0527     Enter or send (unreliable)
           KEY_SRESET     0530     soft (partial) reset (unreliable)
           KEY_RESET      0531     reset or hard reset (unreliable)
           KEY_PRINT      0532     print or copy
           KEY_LL         0533     home down or bottom (lower left)

      WARNING
           The plotting library plot(3X) and the curses library
           curses(3X) 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(3X) code, and/or #undef move() and erase() in the
           plot(3X) code.









      Page 6                                         (73 A2 02MTA REV1)



