1 02/08/88  CURSES Entrypoints
  2 
  3 This section describes all the routines available to the programmer
  4 in the CURSES package.  The routines are organized by function.  For
  5 an alphabetical list, see the information segment curses.gi.info.
  6 
  7 
  8 Structure:
  9 
 10 All programs using CURSES should include the file <curses.h>.  This
 11 file defines several CURSES functions as macros, and defines several
 12 global variables and the datatype WINDOW.  References to windows are
 13 always of type WINDOW *.  CURSES also defines WINDOW * constants
 14 stdscr (the standard screen, used as a default to routines expecting
 15 a window), and curscr (the current screen, used only for certain low
 16 level operations like clearing and redrawing a garbaged screen).
 17 
 18 
 19 Integer constants LINES and COLS are defined, containing the size of
 20 the screen.  Constants TRUE and FALSE are defined, with values 1 and
 21 0, respectively.  Additional constants which are values returned from
 22 most CURSES functions are ERR and OK.  OK is returned if the function
 23 could be properly completed, and ERR is returned if there was some
 24 error, such as moving the cursor outside of a window.
 25 
 26 The include file <curses.h> automatically includes <stdio.h> and an
 27 appropriate tty driver interface file, currently either <sgtty.h> or
 28 <termio.h>.
 29 
 30 
 31 A program using CURSES should include -lib
 32 >sl3p>cl>e>libcurses.archive in the cc command.  This is true for
 33 both the terminfo level and CURSES level.  The compilation flag -def
 34 MINICURSES can be included if you restrict your program to a small
 35 subset of CURSES concerned primarily with screen output and
 36 optimization.  The routines possible with MINICURSES are listed in
 37 the info segment curses.gi.info.  (MINICURSES routines are those in
 38 the list marked with asterisks.)
 39 
 40 
 41 Initialization:
 42 
 43 These functions are called when initializing a program.
 44 
 45 initscr() The first function called should always be initscr.  This
 46 will determine the terminal type and initialize CURSES data
 47 structures.  initscr also arranges that the first call to refresh
 48 will clear the screen.
 49 
 50 endwin() A program should always call endwin before exiting.  This
 51 function will restore tty modes, move the cursor to the lower left
 52 corner of the screen, reset the terminal into the proper non-visual
 53 mode, and tear down all appropriate date structures.
 54 
 55 
 56 newterm(type, fd) A program which outputs to more than one terminal
 57 should use newterm instead of initscr.  newterm should be called once
 58 for each terminal.  It returns a variable of type SCREEN * which
 59 should be saved as a reference to that terminal.  The arguments are
 60 the type of the terminal (a string) and a stdio file descriptor
 61 (FILE*) for output to the terminal.  The file descriptor should be
 62 open for both reading and writing if input from the terminal is
 63 desired.  The program should also call endwin for each terminal being
 64 used (see set_term below).  If an error occurs, the value NULL is
 65 returned.
 66 
 67 
 68 set_term(new)
 69 This function us used to switch to a different terminal.  The screen
 70 reference new becomes the new current terminal.  The previous
 71 terminal is returned by the function.  All other calls affect only
 72 the current terminal.
 73 
 74 longname()
 75 This function returns a pointer to a static area containing a verbose
 76 description of the current terminal.  It is defined only after a call
 77 to initscr, newterm, or setupterm.
 78 
 79 
 80 Option Setting:
 81 
 82 These functions set options within CURSES.  In each case, win is the
 83 window affected, and bf is a boolean flag with value TRUE or FALSE
 84 indicating whether to enable or disable the option.  All options are
 85 initially FALSE.  It is not necessary to turn these options off
 86 before calling endwin.
 87 
 88 clearok(win,bf)
 89 If set, the next call to wrefresh with this window will clear the
 90 screen and redraw the entire screen.  If win is curscr, the next call
 91 to wrefresh with any window will cause the screen to be cleared.
 92 This is useful when the contents of the screen are uncertain, or in
 93 some cases for a more pleasing visual effect.
 94 
 95 
 96 idlok(win,bf)
 97 If enabled, CURSES will consider using the hardware insert/delete
 98 line feature of terminals so equipped.  If disabled, CURSES will
 99 never use this feature.  The insert/delete character feature is
100 always considered.  Enable this option only if your application needs
101 insert/delete line, for example, for a screen editor.  It is disabled
102 by default because insert/delete line tends to be visually annoying
103 when used in applications where it isn't really needed.  If
104 insert/delete line cannot be used, CURSES will redraw the changed
105 portions of all lines that do not match the desired line.
106 
107 
108 keypad(win,bf)
109 This option enables the keypad of the users terminal.  If enabled,
110 the user can press a function key (such as an arrow key) and getch
111 will return a single value representing the function key.  If
112 disabled, CURSES will not treat function keys specially.  If the
113 keypad in the terminal can be turned on (made to transmit) and off
114 (made to work locally), turning on this option will turn on the
115 terminal keypad.
116 
117 leaveok(win,bf)
118 Normally, the hardware cursor is left at the location of the window
119 cursor being refreshed.  This option allows the cursor to be left
120 wherever the update happens to leave it.  It is useful for
121 applications where the cursor is not used, since it reduces the need
122 for cursor motions.  If possible, the cursor is made invisible when
123 this option is enabled.
124 
125 
126 meta(win,bf)
127 If enabled, characters returned by getch are transmitted with all 8
128 bits, instead of stripping the highest bit.  The value OK is returned
129 if the request succeeded, the value ERR is returned if the terminal
130 or system is not capable of 8-bit input.
131 
132 Meta mode is useful for extending the non-text command set in
133 applications where the terminal has a meta shift key.  CURSES takes
134 whatever measures are necessary to arrange for 8-bit input.  On other
135 versions of UNIX systems, raw mode will be used.  On our systems, the
136 character size will be set to 8, parity checking disabled, and
137 stripping of the 8th bit turned off.
138 
139 
140 Note that 8-bit input is a fragile mode.  Many programs and networks
141 only pass 7 bits.  If any link in the chain from the terminal to the
142 application program strips the 8th bit, 8-bit input is impossible.
143 
144 
145 nodelay(win,bf)
146 This option causes getch to be a non-blocking call.  If no input is
147 ready, getch will return -1.  If disabled, getch will hang until a
148 key is pressed.
149 
150 intrflush(win bf)
151 If this option is enabled when an interrupt key is pressed on the
152 keyboard (interrupt, quit, suspend), all output in the tty driver
153 queue will be flushed, giving the effect of faster response to the
154 interrupt but causing CURSES to have the wrong idea of what is on the
155 screen.  Disabling the option prevents the flush.  The default is for
156 the option to be enabled.  This option depends on support in the
157 underlying teletype driver.
158 
159 
160 typeahead(fd)
161 Sets the file descriptor for typeahead check.  fd should be an
162 integer returned from open or fileno.  Setting typeahead to -1 will
163 disable typeahead check.  By default, file descriptor 0(stdin) is
164 used.  Typeahead is checked independently for each screen, and for
165 multiple interactive terminals it should probably be set to the
166 appropriate input for each screen.  A call to typeahead always
167 affects only the current screen.
168 
169 
170 scrollok(win,bf)
171 This option controls what happens when the cursor of a window is
172 moved off the edge of the window, either from a newline on the bottom
173 line, or typing the last character of the last line.  If disabled,
174 the cursor is left on the bottom line.  If enabled, wrefresh is
175 called on the window, and then the physical terminal and window are
176 scrolled up one line.  Note that in order to get the physical
177 scrolling effect the terminal, it is also necessary to call idlok.
178 
179 setscrreg(t,b)
180 wsetscrreg(win,t,b)
181 These functions allow the user to set a software scrolling region in
182 a window win or stdscr.  t and b are the line numbers of the top and
183 bottom margin of the scrolling region.  (Line 0 is the top line of
184 the window.) If this option and scrollok are enabled, an attempt to
185 
186 
187 move off the bottom margin line will cause all lines in the scrolling
188 region to scroll up one line.  Note that this has nothing to do with
189 use of a physical scrolling region capability in the terminal, like
190 that in the VT100.  Only the text of the window is scrolled.  If
191 idlok is enabled and the terminal has either a scrolling region or
192 insert/delete line capability, they will probably be used by the
193 output routines.
194 
195 
196 Terminal Mode Setting:
197 
198 These functions are used to set modes in the tty driver.  The initial
199 mode usually depends on the setting when the program was called: the
200 initial modes documented here represent the normal situation.
201 
202 cbreak()
203 nocbreak()
204 These two functions put the terminal into and out of CBREAK mode.  In
205 this mode, characters typed by the user are immediately available to
206 the program.  When out of this mode, the teletype driver will buffer
207 characters typed until newline is typed.  Interrupt and flow control
208 characters are unaffected by this mode.  Initially the terminal is
209 not in CBREAK mode.  Most interactive programs using CURSES will set
210 this mode.
211 
212 
213 echo()
214 noecho()
215 These functions control whether characters typed by the user are
216 echoed as typed.  Initially, characters typed are echoed by the
217 teletype driver.  Authors of many interactive programs prefer to do
218 their own echoing in a controlled area of the screen, or not to echo
219 at all, so they disable echoing.
220 
221 nl()
222 nonl()
223 These functions control whether newline is translated into carriage
224 return and linefeed on output, and whether return is translated into
225 newline on input.  Initially, the translations do occur.  By
226 disabling these translations, CURSES is able to make better use of
227 the linefeed capability, resulting in faster cursor motion.
228 
229 
230 raw()
231 noraw()
232 The terminal is placed into or out of raw mode.  Raw mode is similar
233 to cbreak mode in that characters typed are immediately passed
234 through to the user program.  The interrupt and quit characters will
235 cause signals on Multics.  RAW mode also causes 8 bit input and
236 output.
237 
238 resetty()
239 savetty()
240 These functions save and restore the state of the tty modes.  savetty
241 saves the current state in a buffer, resetty restores the state to
242 what it was at the last call to savetty.
243 
244 
245 Window Manipulation:
246 
247 newwin (num_lines, num_cols, beg_row, beg_col)
248 Create a new window with the given number of lines and columns.  The
249 upper left corner of the window is at line beg_row column beg_col.
250 If either num_lines or num_cols is zero, they will be defaulted to
251 LINES-beg_row and COLS-beg_col.  A new full-screen window is created
252 by calling newwin (0,0,0,0).
253 
254 newpad(num_lines, num_cols)
255 Creates a new pad data structure.  A pad is like a window, except
256 that it is not restricted by the screen size, and is not associated
257 with a particular part of the screen.  Pads can be used when a large
258 window is needed, and only a part of the window will be on the screen
259 at one time.  Automatic refreshes of pads (e.g.  from scrolling
260 
261 
262 or echoing of input) do not occur.  It is not legal to call refresh
263 with a pad as an argument, the routines prefresh or pnoutrefresh
264 should be called instead.  Note that these routines require
265 additional parameters to specify the part of the pad to be displayed
266 and the location on the screen to be used for display.
267 
268 subwin (orig, num_lines, num_cols, begy, begx)
269 Create a new window with the given number of lines and columns.  The
270 window is at position (begy, begx) on the screen.  (It is relative to
271 the screen, not orig.) The window is made in the middle of the window
272 orig, so that changes made to one window will affect both windows.
273 When using this function, often it will be necessary to call touchwin
274 before calling wrefresh.
275 
276 
277 delwin(win)
278 Deletes the named window, freeing up all memory associated with it.
279 In the case of overlapping windows, subwindows should be deleted
280 before the main window.
281 
282 mvwin(win, br, bc)
283 Move the window so that the upper left corner will be at position
284 (br, bc).  If the move would cause the window to be off the screen,
285 it is an error and the window is not moved.
286 
287 
288 touchwin(win)
289 Throw away all optimization information about which parts of the
290 window have been touched, by pretending the entire window has been
291 drawn on.  This is sometimes necessary when using overlapping
292 windows, since a change to one window will affect the other window,
293 but the records of which lines have been changed in the other window
294 will not reflect the change.
295 
296 overlay(win1, win2)
297 overwrite(win1, win2)
298 These functions overlay win1 on top of win2; that is, all text in
299 win1 is copied into win2.  The difference is that overlay is
300 nondestructive (blanks are not copied) while overwrite is
301 destructive.
302 
303 
304 Causing Output to the Terminal:
305 
306 refresh()
307 wrefresh(win)
308 These functions must be called to get any output on the terminal, as
309 other routines merely manipulate data structures.  wrefresh copies
310 the named window to the physical terminal screen, taking into account
311 what is already there in order to do optimizations.  refresh is the
312 same, using stdscr as a default screen.  Unless leaveok has been
313 enabled, the physical cursor of the terminal is left at the location
314 of the window's cursor.
315 
316 
317 doupdate() wnoutrefresh(win)
318 These two functions allow multiple updates with more efficiency than
319 wrefresh.  To use them, it is important to understand how CURSES
320 works.  In addition to all the window structures, CURSES keeps two
321 data structures representing the terminal screen: a physical screen,
322 describing what is actually on the screen, and a virtual screen,
323 describing what the programmer wants to have on the screen.  wrefresh
324 works by first copying the named window to the virtual screen
325 (wnoutrefresh), and then calling the routine to update the screen
326 (doupdate).  If the programmer wishes to output several windows at
327 once, a series of calls to wrefresh will result in alternating calls
328 to wnoutrefresh and doupdate, causing several bursts of output to the
329 screen.  By calling wnoutrefresh for each window, it is then possible
330 to call doupdate once, resulting in only one burst of output, with
331 probably fewer total characters transmitted.
332 
333 
334 prefresh(pad,pminrow,pmincol,sminrow,smincol,smaxrow smaxcol)
335 pnoutrefresh(pad,pminrow,pmincol,sminrow,smincol,smaxrow,smaxcol)
336 These routines are analogous to wrefresh and wnoutrefresh except that
337 pads, instead of windows, are involved.  The additional parameters
338 are needed to indicate what part of the pad and screen are involved.
339 pminrow and pmincol specify the upper left corner, in the pad, of the
340 rectangle to be displayed.  sminrow, smincol, smaxrow, and smaxcol
341 specify the edges, on the screen, of the rectangle to be displayed
342 in.  The lower right corner in the pad of the rectangle to be
343 displayed is calculated from the screen coordinates, since the
344 rectangles must be the same size.  Both rectangles must be entirely
345 contained within their respective structures.
346 
347 
348 Writing on Window Structures:
349 
350 These routines are used to "draw " text on windows.  In all cases, a
351 missing win is taken to be stdscr.  y and x are the row and column,
352 respectively.  The upper left corner is always (0,0), not (1,1).  The
353 mv functions imply a call to move before the call to the other
354 function.
355 
356 Moving the Cursor
357 
358 move(y, x)
359 wmove(win, y, x)
360 The cursor associated with the window is moved to the given location.
361 This does not move the physical cursor of the terminal until refresh
362 is called.  The position specified is relative to the upper left
363 corner of the window.
364 
365 
366 Writing One Character
367 
368 addch(ch)
369 waddch(win, ch)
370 mvaddch(y,x,ch)
371 mvwaddch(win,y,x,ch)
372 The character ch is put in the window at the current cursor position
373 of the window.  If ch is a tab, newline, or backspace, the cursor
374 will be moved appropriately in the window.  If ch is a different
375 control character, it will be drawn in the ^X notation.  The position
376 of the window cursor is advanced.  At the right margin, an automatic
377 newline is performed.  At the bottom of the scrolling region, if
378 scrollok in enabled, the scrolling region will be scrolled up one
379 line.
380 
381 
382 The ch parameter is actually an integer, not a character.  Video
383 attributes can be combined with a character by or-ing them into the
384 parameter.  This will result in these attributes also being set.
385 (The intent here is that text, including attributes, can be copied
386 from one place to another with inch and addch.)
387 
388 Writing a String
389 
390 addstr(str)
391 waddstr(win,str)
392 mvaddstr(y,x,str)
393 mvwaddstr(win,y,x,str)
394 These functions write all the characters of the null terminated
395 character string str on the given window.  They are identical to a
396 series of calls to addch.
397 
398 
399 Clearing Areas of the Screen
400 
401 erase()
402 werase(win)
403 These functions copy blanks to every position in the window.
404 
405 clear()
406 wclear(win)
407 These functions are like erase and werase but they also call clearok,
408 arranging that the screen will be cleared on the next call to refresh
409 for that window.
410 
411 
412 clrtobot()
413 wclrtobot(win)
414 All lines below the cursor in this window are erased.  Also, the
415 current line to the right of the cursor is erased.
416 
417 clrtoeol()
418 wclrtoeol(win)
419 The current line to the right of the cursor is erased.
420 
421 
422 Inserting and Deleting Text:
423 
424 delch()
425 wdelch(win)
426 mvdelch(y,x)
427 mvwdelch(win,y,x)
428 The character under the cursor in the window is deleted.  All
429 characters to the right on the same line are moved to the left one
430 position.  This does not imply use of the hardware delete character
431 feature.
432 
433 
434 deleteln()
435 wdeleteln(win)
436 The line under the cursor in the window is deleted.  All lines below
437 the current line are moved up one line.  The bottom line of the
438 window is cleared.  This does not imply use of the hardware delete
439 line feature.
440 
441 insch(c)
442 winsch(win,c)
443 mvinsch(y,x,c)
444 mvwinsch(win,y,x,c)
445 The character c is inserted before the character under the cursor.
446 All characters to the right are moved one space to the right,
447 possibly losing the rightmost character on the line.  This does not
448 imply use of the hardware insert character feature.
449 
450 
451 insertln()
452 winsertln(win)
453 A blank line is inserted above the current line.  The bottom line is
454 lost.  This does not imply use of the hardware insert line feature.
455 
456 
457 Formatted Output:
458 
459 printw(fmt, args)
460 wprintw(win, fmt, args)
461 mvprintw(y, x, fmt, args)
462 mvwprintw(win, y, x, fmt, args)
463 These functions correspond to printf.  The characters which would be
464 output by printf are instead output using waddch on the given window.
465 
466 
467 Miscellaneous:
468 
469 box(win, vert, hor)
470 A box is drawn around the edge of the window.  vert and hor are the
471 characters the box is to be drawn with.
472 
473 scroll(win)
474 The window is scrolled up one line.  This involves moving the lines
475 in the window data structure.  As an optimization, if the window is
476 stdscr and the scrolling region is the entire window, the physical
477 screen will be scrolled at the same time.
478 
479 
480 Input From a Window:
481 
482 getyx(win,y,x)
483 The cursor position of the window is placed in the two integer
484 variables y and x.  Since this is a macro, no & is necessary.
485 
486 inch()
487 winch(win)
488 mvinch(y,x)
489 mvwinch(win,y,x)
490 The character at the current position in the named window is
491 returned.  If any attributes are set for that position, their values
492 will be or-ed into the value returned.  The pre-defined constants
493 A_ATTRIBUTES and A_CHARTEXT can be used with the & operator to
494 extract the character or attributes alone.
495 
496 
497 Input From The Terminal:
498 
499 getch()
500 wgetch(win)
501 mvgetch(y,x)
502 mvwgetch(win,y,x)
503 A character is read from the terminal associated with the window.  In
504 a nodelay mode, if there is no input waiting, the value -1 is
505 returned.  In delay mode, the program will hang until the system
506 passes text through to the program.  Depending on the setting of
507 cbreak, this will be after one character, or after the first newline.
508 
509 If keypad mode is enabled, and a function key is pressed, the code
510 for that function key will be returned instead of the raw characters.
511 Possible function keys are defined with integers beginning with
512 
513 
514 0401, whose names begin with KEY_.  These are listed in "Input" under
515 "INTRODUCTION." If a character is received that could be the
516 beginning of a function key (such as escape), CURSES will set a 1-
517 second timer.  If the remainder of the sequence does not come in
518 within 1 second, the character will be passed through, otherwise the
519 function key value will be returned.  For this reason, on many
520 terminals, there will be a one second delay after a user presses the
521 escape key.  (Use by a programmer of the escape key for a single
522 character function is discouraged.)
523 
524 
525 getstr(str)
526 wgetstr(win,str)
527 mvgetstr(y,x,str)
528 wvwgetstr(win,y,x,str)
529 A series of calls to getch is made, until a newline is received.  The
530 resulting value is placed in the area pointed at by the character
531 pointer str.  The users' erase and kill characters are interpreted.
532 
533 scanw(fmt, args)
534 wscanw(win, fmt, args)
535 mvscanw(y, x, fmt, args)
536 mvwscanw(win, y, x, fmt, args)
537 This function corresponds to scanf.  wgetstr is called on the window,
538 and the resulting line is used as input for the scan.
539 
540 
541 Video Attributes:
542 
543 attroff(attrs)
544 wattroff(win, attrs)
545 attron(attrs)
546 wattron(win, attrs)
547 attrset(attrs)
548 wattrset(win, attrs)
549 standout()
550 standend()
551 wstandout(win)
552 wstandend(win)
553 These functions set the current attributes of the named window.
554 These attributes can be any combination of A_STANDOUT, A_REVERSE,
555 
556 
557 A_BOLD, A_DIM, A_BLINK, and A_UNDERLINE.  These constants are defined
558 in <curses.h> and can be combined with the C | (or) operator.
559 
560 The current attributes of a window are applied to all characters that
561 are written into the window with waddch.  Attributes are a property
562 of the character, and move with the character through any scrolling
563 and insert/delete line/character operations.  To the extent possible
564 on the particular terminal, they will be displayed as the graphic
565 rendition of characters put on the screen.
566 
567 attrset(attrs) sets the current attributes of the given window to
568 attrs.  attroff(attrs) turns off the named attributes without
569 affecting any other attributes.  attron(attrs) turns on the named
570 attributes without affecting any others.  standout is the same as
571 attron(A_STANDOUT).  standend is the same as attrset(0) in that it
572 turns off all attributes.
573 
574 
575 Bells and Flashing Lights:
576 
577 beep()
578 flash()
579 These functions are used to signal the programmer.  beep will sound
580 the audible alarm on the terminal, if possible, and if not, will
581 flash the screen (visible bell), if that is possible.  flash will
582 flash the screen, and if that is not possible, will sound the audible
583 signal.  If neither signal is possible nothing will happen.  Nearly
584 all terminals have an audible signal (bell or beep) but only some can
585 flash the screen.
586 
587 
588 Portability Functions:
589 
590 These functions do not directly involve terminal dependent character
591 output but tend to be needed by programs that use CURSES.
592 Unfortunately, their implementation varies from one system to
593 another.  They have been included here to enhance the portability of
594 programs using CURSES.
595 
596 baudrate()
597 baudrate returns the output speed of the terminal.  The number
598 returned is the integer baud rate, for example, 9600, rather than a
599 table index such as B9600.
600 
601 
602 erasechar()
603 The erase character chosen by the user is returned.  This is the
604 character typed by the user to erase the character just typed.
605 
606 killchar()
607 The line kill character chosen by the user is returned.  This is the
608 character typed by the user to forget the entire line being typed.
609 
610 flushinp()
611 flushinp throws away any typeahead that has been typed by the user
612 and has not yet been read by the program.
613 
614 
615 Delays:
616 
617 These functions are highly unportable, but are often needed by
618 programs that use CURSES, especially real time response programs.
619 Some of these functions require a particular operating system or a
620 modification to the operating system to work.  In all cases, the
621 routine will compile and return an error status if the requested
622 action is not possible.  It is recommended that programmers avoid use
623 of these functions if possible.
624 
625 draino(ms)
626 The program is suspended until the output queue has drained enough to
627 complete in ms additional milliseconds.  Thus, draino(50) at 1200
628 baud would pause until there are no more than 6 characters in the
629 output queue, because it would take 50 milliseconds to output the
630 
631 
632 additional 6 characters.  The purpose of this routine is to keep the
633 program (and thus the keyboard) from getting ahead of the screen.  If
634 the operating system does not support the ioctls needed to implement
635 draino, the value ERR is returned; otherwise, OK is returned.
636 
637 napms(ms)
638 This function suspends the program for ms milliseconds.  It is
639 similar to sleep except with higher resolution.  The resolution
640 actually provided will vary with the facilities available in the
641 operating system, and often a change to the operating system will be
642 necessary to produce good results.  If resolution of at least .1
643 second is not possible, the routine will round to the next higher
644 second, call sleep, and return ERR.  Otherwise, the value OK is
645 returned.  Often the resolution provided is 1/60th second.
646 
647 
648 Lower Level Functions:
649 
650 These functions are provided for programs not needing the screen
651 optimization capabilities of CURSES.  Programs are discouraged from
652 working at this level, since they must handle various glitches in
653 certain terminals.  However, a program can be smaller if it only
654 brings in the low level routines.
655 
656 
657 Cursor Motion
658 
659 mvcur(oldrow, oldcol, newrow, newcol)
660 This routine optimally moves the cursor from (oldrow, oldcol) to
661 (newrow, newcol).  The user program is expected to keep track of the
662 current cursor position.  Note that unless a full screen image is
663 kept, CURSES will have to make pessimistic assumptions, sometimes
664 resulting in less than optimal cursor motion.  For example, moving
665 the cursor a few spaces to the right can be done by transmitting the
666 characters being moved over, but if CURSES does not have access to
667 the screen image, it doesn't know what these characters are.
668 
669 
670 TERMINFO Level:
671 
672 These routines are called by low level programs that need access to
673 specific capabilities of terminfo.  A program working at this level
674 should include both <curses.h> and <term.h> in that order.  After a
675 call to setupterm, the capabilities will be available with macro
676 names defined in <term.h>.  See terminal_information.gi.info for a
677 detailed description of the capabilities.
678 
679 Boolean valued capabilities will have the value 1 if the capability
680 is present, 0 if it is not.  Numeric capabilities have the value -1
681 if the capability is missing, and have a value at least 0 if it is
682 present.  String capabilities (both those with and without
683 parameters) have the value NULL if the capability is missing, and
684 otherwise have type char * and point to a character string containing
685 
686 
687 the capability.  The special character codes involving the \ and ^
688 characters (such as \r for return, or ^A for control A) are
689 translated into the appropriate ASCII characters.  Padding
690 information (of the form $<time>) and parameter information
691 (beginning with %) are left uninterpreted at this stage.  The routine
692 tputs interprets padding information, and tparm interprets parameter
693 information.
694 
695 If the program only needs to handle one terminal, the definition -
696 def SINGLE can be passed to the C compiler, resulting in static
697 references to capabilities instead of dynamic references.  This can
698 result in smaller code, but prevents use of more than one terminal at
699 a time.  Very few programs use more than one terminal, so almost all
700 programs can use this flag.
701 
702 
703 setupterm(term, filenum, errret)
704 This routine is called to initialize a terminal.  term is the
705 character string representing the name of the terminal being used.
706 filenum is the UNIX file descriptor of the terminal being used for
707 output.  errret is a pointer to an integer in which a success or
708 failure indication is returned.  The values returned can be 1 (all is
709 well), 0 (no such terminal), or -1 (some problem locating the
710 terminfo database).  The value of term can be given as NULL, which
711 will cause the value of TERM in the environment to be used.  The
712 errret pointer can also be given as NULL, meaning no error code is
713 wanted.  If errret is defaulted, and something goes wrong, setupterm
714 will print an appropriate error message and exit, rather than
715 returning.  Thus, a simple program can call setupterm(NULL, 1, NULL)
716 and not worry about initialization errors.
717 
718 
719 If the variable TERMINFO is set in the environment to a path name,
720 setupterm will check for a compiled terminfo description of the
721 terminal under that path, before checking the standard system
722 terminfo description.  Otherwise, only the standard system terminfo
723 description is checked.
724 
725 setupterm will check the tty driver mode bits, using filenum, and
726 change any that might prevent the correct operation of other low
727 level routines.  Currently, the mode that expands tabs into spaces is
728 disabled, because the tab character is sometimes used for different
729 functions by different terminals.  (Some terminals use it to move
730 right one space.  Others use it to address the cursor to row or
731 column 9.) If the system is expanding tabs, setupterm will remove the
732 definition of the tab and backtab functions, making the assumption
733 
734 
735 that since the user is not using hardware tabs, they may not be
736 properly set in the terminal.  Other system dependent changes, such
737 as disabling a virtual terminal driver, may be made here.
738 
739 As a side effect, setupterm initializes the global variable ttytype,
740 which is an array of characters, to the value of the list of names
741 for the terminal, This list comes from the beginning of the terminfo
742 description.
743 
744 After the call to setupterm, the global variable cur_term is set to
745 point to the current structure of terminal capabilities.  By calling
746 setupterm for each terminal, and saving and restoring cur_term, it is
747 possible for a program to use two or more terminals at once.
748 
749 
750 The mode that turns newlines into CRLF on output is not disabled.
751 Programs that use cursor_down or scroll_forward should avoid these
752 capabilities if their value is linefeed unless they disable this
753 mode.  setupterm calls reset_prog_mode after any changes it makes.
754 
755 
756 reset_prog_mode()
757 reset_shell_mode()
758 def_prog_mode()
759 def_shell_mode()
760 These routines can be used to change the tty modes between the two
761 states: shell (the mode they were in before the program was started)
762 and program (the mode needed by the program).  def_prog_mode saves
763 the current terminal mode as program mode.  setupterm and initscr
764 call def_shell_mode automatically.  reset_prog_mode puts the terminal
765 into program mode, and reset_shell_mode puts the terminal into normal
766 mode.
767 
768 A typical calling sequence is for a program to call initscr (or
769 setupterm if a terminfo level program), then to set the desired
770 program mode by calling routines such as cbreak and noecho, then to
771 
772 
773 call def_prog_mode to save the current state.  Before a shell escape
774 or control-Z suspension, the program should call reset_shell_mode, to
775 restore normal mode for the shell.  Then, when the program resumes,
776 it should call reset_prog_mode.  Also, all programs must call
777 reset_shell_mode before they exit.  (The higher level routine endwin
778 automatically calls reset_shell_mode.)
779 
780 Normal mode is stored in cur_term->Ottyb, and program mode is in
781 cur_term->Nttyb.  These structures are both of type termio (which
782 varies depending on the system).
783 
784 
785 vidputs(newmode, putc)
786 newmode is any combination of attributes, defined in <curses.h>.
787 putc is a putchar-like function.  The proper string to put the
788 terminal in the given video mode is output.  The previous mode is
789 remembered by this routine.  The result characters are passed through
790 putc.
791 
792 vidattr(newmode)
793 The proper string to put the terminal in the given mode is output to
794 stdout.
795 
796 
797 tparm(instring, p1,p2,p3,p4,p5,p6,p7,p8,p9)
798 tparm is used to instantiate a parameterized string.  The character
799 string returned has the given parameters applied, and is suitable for
800 tputs.  Up to 9 parameters can be passed, in addition to the
801 parameterized string.
802 
803 
804 tputs(cp,affcnt,outc)
805 A string capability, possibly containing padding information, is
806 processed.  Enough padding characters to delay for the specified time
807 replace the padding specification, and the resulting string is
808 passed, one character at a time, to the routine outc, which should
809 expect one character parameter.  (This routine often just calls
810 putchar.) cp is the capability string.  affcnt is the number of units
811 affected by the capability, which varies with the particular
812 capability.  (For example, the affcnt for insert_line is the number
813 of lines below the inserted line on the screen, that is, the number
814 of lines that will have to be moved by the terminal.) affcnt is used
815 by the padding information of some terminals as a multiplication
816 factor.  If the capability does not have a factor, the value 1 should
817 be passed.
818 
819 
820 putp(str)
821 This is a convenient function to output a capability with no affcnt.
822 The string is output to putchar with an affcnt of 1.  It can be used
823 in simple applications that do not need to process the output of
824 tputs.
825 
826 delay_output(ms)
827 A delay is inserted into the output stream for the given number of
828 milliseconds.  The current implementation inserts sufficient pad
829 characters for the delay.  This should not be used in place of a high
830 resolution sleep, but rather for delay effects in the output.  Due to
831 buffering in the system, it is unlikely that this call will result in
832 the process actually sleeping.  Since large numbers of pad characters
833 can be output, it is recommended that ms not exceed 500.