curses(3X) curses(3X)NAME curses - CRT screen handling and optimization package SYNOPSIS #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 terminal 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 as a C structure. These data structures are manipulated with functions described later, 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.) Eventually refresh() must be called, telling the routines to make the users CRT screen look like stdscr. ``Mini-Curses'' is a subset of curses which does not allow manipulation of more than one window. To invoke this subset, use -DMINICURSES as a cc option. This level is smaller and faster than full curses. 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 the file /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/paul/myterms, curses will first check /usr/paul/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. January 1992 1
curses(3X) curses(3X)Functions Routines listed here may be called when using the full curses. Those marked with a plus (+) are macros. Those marked with an asterisk (*) may be called when using Mini- 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 in attrs. attron(attrs)*+ Turn on attributes named in attrs. 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 characters to use for vertical and horizontal 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()+ 2 January 1992
curses(3X) curses(3X)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 sound beep. flushinp()* Throw away any typeahead. getch()*+ Get a character from tty. getstr(str) Get a string through stdscr. gettmode() Establish current tty modes. getyx(win,y,x)+ Get y,x coordinates. 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 is nonzero. January 1992 3
curses(3X) curses(3X)inch()+ Get character at current y,x coordinates. initscr()* Initialize screens. insch(c) Insert a character. 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 is nonzero. for win; otherwise cursor must be remain at current position. longname() Return verbose name of terminal. meta(win,flag)* Allow metacharacters on input if flag is nonzero. move(y,x)*+ Move to y,x on stdscr. mvaddch(y,x,ch)+ move(y,x), then addch(ch). mvaddstr(y,x,str)+ move(y,x), then addstr(str). mvcur(oldrow,oldcol,newrow,newcol) Low level cursor motion. mvdelch(y,x)+ Like delch, but move(y,x) first. mvgetch(y,x)+ Like getch, but move(y,x) first. mvgetstr(y,x)+ Like getstr, but move(y,x) first. 4 January 1992
curses(3X) curses(3X)mvinch(y,x)+ Like inch, but move(y,x) first. mvinsch(y,x,c) Like insch, but move(y,x) first. mvprintw(y,x,fmt,args)+ Like printw, but move(y,x) first. mvscanw(y,x,fmt,args) Like scanw, but move(y,x) first. mvwaddch(win,y,x,ch)+ Like addch, but move(y,x) first. mvwaddstr(win,y,x,str)+ Like waddstr, but move(y,x) first. mvwdelch(win,y,x)+ Like wdelch, but move(y,x) first. mvwgetch(win,y,x)+ Like wgetch, but move(y,x) first. mvwgetstr(win,y,x)+ Like wgetstr, but move(y,x). mvwin(win,by,bx) Like win, but move(y,x). mvwinch(win,y,x)+ Like winch, but move(y,x). mvwinsch(win,y,x,c)+ Like winsch, but move(y,x). mvwprintw(win,y,x,fmt,args)+ Like wprintw, but move(y,x). mvwscanw(win,y,x,fmt,args)+ Like wscanw, but move(y,x). newpad(nlines,ncols) Create a new pad with given dimensions. newterm(type,fd) Set up new terminal of a given type to output on fd. newin(lines,cols,begin_y,begin_x) Create a new window. nl()* January 1992 5
curses(3X) curses(3X)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 is called. prefresh(pad,pminrow,pmincol,sminrow,smincol, smaxrow,smaxcol) Refresh from pad, starting from given upper left corner of pad, with output to the 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. 6 January 1992
curses(3X) curses(3X)scanw(fmt,arg1,arg2,...) scanf through stdscr. scroll(win) Scroll win one line. scrollok(win,flag) Allow terminal to scroll if flag is nonzero. 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. 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 character to win. waddstr(win,str) Add string to win. wattroff(win,attrs) Turn off attrs in win. wattron(win,attrs) January 1992 7
curses(3X) curses(3X)Turn on attrs in win. wattrst(win,attrs) Set attributes 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 character from win. wdeleteln(win) Delete line from win. werase(win) Erase win. wgetch(win) Get a character through win. wgetstr(win,str) Get a string through win. winch(win)+ Get character at current y,x in win. winsch(win,c) Insert character into win. winsertln(win) Insert line into win. wmove(win,y,x) Set current y,x coordinates 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. 8 January 1992
curses(3X) curses(3X)wsetscrreg(win,t,b) Set scrolling region of win. wstandend(win) Clear standout attribute in win. wstandout(win) Set standout attribute in win. The terminfo level routines These routines should be called by programs wishing to deal directly with the terminfo database; however, due to the low level of this interface, it is discouraged. Initially, setupterm should be called, which 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. Parameterized 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 tty modes. (Programs desiring shell escapes or suspention 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 and all output is to 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 parameters pi. tputs(str,affcnt,putc) Apply padding info to string str. The argument 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) January 1992 9
curses(3X) curses(3X)Handy function that calls tputs(str,1,putchar). vidputs(attrs,putc) Output the string to put the terminal in video attribute mode attrs, which is any combination of the attributes listed later. Characters are passed to putchar-like function, putc. vidattr(attrs) Like vidputs but outputs through putchar. The termcap compatibility routines These routines were included as a conversion aid for programs that use termcap. Their parameters are the same as for termcap, and they are emulated using the terminfo database. They may be dispensed with 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 parameters 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) 10 January 1992
curses(3X) curses(3X)A_PROTECT Protected 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) KEYDOWN 0402 Arrow key down KEY_UP 0403 Arrow key up KEYLEFT 0404 Arrow key left KEY_RIGHT 0405 Arrow key right KEYHOME 0406 Home key (upward+left arrow) KEY_BACKSPACE 0407 Backspace (unreliable) KEYF0 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 character or enter insert mode KEY_EIC 0514 Exit insert character 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 backward (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) WARNINGS 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 or #undef move() and erase() in the plot(3X)) code. Similarly, move is also a macro in <sys/pcl.h>. January 1992 11
curses(3X) curses(3X)SEE ALSO curses5.0(3X), terminfo(4) 12 January 1992