Subject: Terminfo/Curses Part 1 of 11 : Run this shell script with "sh" not "csh" PATH=:/bin:/usr/bin:/usr/ucb export PATH if test ! -d =doc then echo 'Making directory "=doc"' mkdir =doc fi echo 'x - =doc/Installation' sed 's/^X//' <<'//go.sysin dd *' >=doc/Installation How to install Curses/Terminfo on your system (Beta-one test release) --------------------------------------------------------------------- Assumptions: You have unpacked the tar-file into an empty directory. You found this file in a subdirectory of that one called '=doc'. There are three other subdirectories, called '=src', '=test', and '=data'. [ Actually, if you recieved this file as part of the mod.sources distribution, you got this distribution as eleven shar format archive files, which (when passed through "sh" to unbundle them) create the exact same source heirarchy - John Nelson (mod.sources)] If any of these assumptions is false, I make no claims for the correctness of the following instructions. 1. Decide where you want to put the object files and source files of terminal descriptions. On our system (and I recommend it for you), the directory /etc/term is used. If you really can't stand the idea (remember, this is not where the C language source code to the library will go; this is where the actual terminal descriptions and their object files will go), you'll need to do these steps (skip these if you're being reasonable or lazy): a. Keep in mind that this directory should probably be in your root filesystem so that programs which use terminfo can be used even when the system is only up single-user. b. Change the value of the variable SRCDIR in =src/Makefile to the name of the directory you've chosen. c. Change the man pages in =doc to reflect the name-change. 2. Copy everything in the subdirectory =data into the directory chosen in step 1. 3. Change to the subdirectory =src and type 'make'. Absolutely no error-messages should be produced. This should compile the library (two versions, normal and debugging), the terminfo compiler and the dump program. Then type 'make install' to copy the header files into /usr/include, copy the compiler and dump programs into the directory chosen in step 1, and copy the versions of the library into /usr/lib. You will probably need to be super-user to do this. 4. Change to the directory chosen in step 1 and type 'make'. This should compile the database. Again, no error-messages of any sort should be produced. 5. Change to the subdirectory =test and type 'make'. This should compile all of the test programs in the release. Once again, there should be no errors. 6. You may want to install the test programs, make copies of the documentation, etc. NOTES: This release of terminfo/curses will not work on any PDP-11 UNIX systems I know of because the Pre-processor to the C compiler can't hack the number of #define's in term.h. If you get this up on an eleven, let me know. Real systems hackers can probably find a nice constant to change in their cpp code, but I hesitate to try to tell you where to find it. The library is stored in /usr/lib/libncurses.a, unless you changed the Makefile. Note the 'n'!! Programs wishing to use the new package should say "-lncurses" on their 'cc' command while those wanting the old package should still say '-lcurses'. Similarly, the curses header file should be included using #include The header file has been included so that programs which work only at the terminfo-level need not worry about name conflicts with the rest of the package. By including instead of , they will get everything needed for the terminfo-level routines. You, dear reader, are truly a guinea pig. If there's anything wrong with this package, these instructions, etc., you're supposed to tell me about it. I'm going to be very depressed if I send this out and get no response at all. So, save me the agony of loneliness and write to me your impressions/complaints/ suggestions! [ actually, this is being posted two years after the original distribution. Most of the bugs should be out, but of course, there are no guarantees - John Nelson (mod.sources) ] Oh, yes. Thank you. Pavel Curtis Computer Science Dept. 405 Upson Hall Cornell University Ithaca, NY 14853 Ph- (607) 256-4934 decvax!cornell!pavel (UUCP) Pavel.Cornell@Udel-Relay (ARPA) //go.sysin dd * echo 'x - =doc/changes.ms' sed 's/^X//' <<'//go.sysin dd *' >=doc/changes.ms X.po +.5i X.TL New Features in Curses and Terminfo X.AU Pavel Curtis X.NH Introduction X.PP This document describes new features that are being added to the Berkeley \fBcurses\fP subroutine package. It also describes the new \fBterminfo\fP database, which replaces the Berkeley \fBtermcap\fP database. The emphasis is on the new features. X.NH New Features in Curses X.PP This section describes the enhancements to curses. Briefly, the enhancements are: X.de Np X.IP \\n+(l%. X.. X.nr l% 0 1 X.af l% a X.Np Curses is smarter. It can take advantage of insert/delete line/character. (By default, it will not use insert/delete line. See \fIidlok()\fR.) X.Np Curses uses the new \fBterminfo\fP data base, as described in the next section. X.Np Curses works on more terminals. X.Np It is possible to use more than one terminal at a time. X.Np Video attributes can be displayed in any combination. X.Np Curses handles terminals with the ``magic cookie'' video attribute glitch. X.Np The function and arrow keys on terminals can be input as though they were a single character. X.Np There is a user accessible scrolling region, like the DEC VT100. X.Np If the programmer restricts his code to a subset of the full curses, the \fBMINICURSES\fP version can be used, which is smaller and faster. X.Np Two routines are provided for setting the tty bits to the proper state for shell escapes and control-Z suspensions. X.Np On systems that support it (currently only 4.1BSD), if the user types something during an update, the update will stop, pending a future update. This is useful when the user hits several keys, each of which causes a good deal of output. X.Np The routine \fBgetstr()\fP is smarter - it handles the users erase and kill characters, and echos its input. X.Np The function \fBlongname()\fP is now useful and actually works. X.Np Nodelay mode allows ``real time'' programs to be written with the same interface on both systems. Setting the flag causes \fBgetch\fP to return -1 if no input is waiting. X.Np Several useful routines are provided to enhance portability. X.NH 2 Curses is Smarter X.PP The algorithm used by curses has been replaced with an algorithm that takes into account insert and delete line and character functions, if available, in the terminal. By default, curses will not use insert/delete line. This was not done for performance reasons, since there is no speed penalty involved. Rather, it was found that some programs do not need this facility, and that if curses uses insert/delete line, the result on the screen can be visually annoying. Since most simple programs using curses do not need this, and since the old curses did not use it, the default is to avoid insert/delete line. Call the routine X.DS \fBidlok(stdscr, TRUE);\fP X.DE to enable insert/delete line, if your application needs it. Insert/delete character is always considered. X.NH 2 Additional Terminals X.PP Curses works on a larger class of terminals than the previous version. Terminfo is able to address the cursor on more kinds of terminals. Curses will work even if absolute cursor addressing is not possible, as long as the cursor can be moved from any location to any other location. It considers local motions, parameterized motions, home, and carriage return. X.PP Curses is still aimed at full duplex, alphanumeric, video terminals. No attempt is made to handle half-duplex, synchronous, hard copy, or bitmapped terminals. X.PP Curses handles terminals with the ``magic cookie glitch'' in their video attributes.\u*\d X.FS \u*\dThis feature is not supported in the current test release. It will be implemented in the official distribution. X.FE This glitch means that a change in video attributes is implemented by storing a ``magic cookie'' in a location on the screen. This ``cookie'' takes up a space, preventing an exact implementation of what the programmer wanted. Curses takes the extra space into account, and moves part of the line to the right, as necessary. In some cases, this will unavoidably result in losing text from the right hand edge of the screen. Existing spaces are taken advantage of. X.NH 2 Multiple Terminals X.PP Some applications need to display text on more than one terminal, controlled by the same process. Even if the terminals are different, the new curses can handle this. X.PP All information about the current terminal is kept in a global variable X.DS \fBstruct screen\fP *SP; X.DE Although the screen structure is hidden from the user, the C compiler will accept declarations of variables which are pointers. The user program should declare one screen pointer variable for each terminal it wishes to handle. The routine X.DS \fBstruct screen * \fInewterm\fR(type, fd) \fBchar\fP *type; XFILE *fp; X.DE will set up a new terminal of the given terminal type which does output on file pointer fp. A call to \fIinitscr()\fP is essentially \fInewterm\fP(\fIgetenv\fP(``TERM''), \fBstdout\fR). A program wishing to use more than one terminal should use \fInewterm()\fP for each terminal and save the value returned as a reference to that terminal. X.PP To switch to a different terminal, call X.DS \fBstruct screen\fP * \fIset_term\fP(term) \fBstruct screen\fP *term; X.DE The old value of SP will be returned. You should not assign directly to SP because certain other global variables must also be changed. X.PP All curses routines always affect the current terminal. To handle several terminals, switch to each one in turn with \fIset_term()\fP, and then access it. Each terminal must be set up with \fInewterm()\fP, and closed down with \fIendwin()\fP. X.NH 2 Video Attributes X.PP Video attributes can be displayed in any combination on terminals with this capability. They are treated as an extension of the standout capability, which is still present. X.PP Each character position on the screen has 16 bits of information associated with it. 7 of these bits are the character to be displayed, leaving separate bits for 9 video attributes. These bits are used for standout, underline, reverse video, blink, dim, bold, blank, protect, and alternate character set. Standout is taken to be whatever highlighting works best on the terminal, and should be used by any program that does not need specific or combined attributes. Underlining, reverse video, blink, dim, and bold are the usual video attributes. Blank means that the character is displayed as a space, for security reasons. Protected and alternate character set are dependent on the particular terminal. The use of these last three bits is subject to change and not recommended. X.PP The routines to use these attributes include X.DS X.ta 2i \fIattrset\fP(attrs) \fIwattrset\fP(attrs) \fIattron\fP(attrs) \fIwattron\fP(attrs) \fIattroff\fP(attrs) \fIwattroff\fP(attrs) \fIstandout\fP() \fIwstandout\fP() \fIstandend\fP() \fIwstandend\fP() X.DE X.PP Attributes, if given, can be any combination of A_STANDOUT, A_UNDERLINE, A_REVERSE, A_BLINK, A_DIM, A_BOLD, A_INVIS, A_PROTECT, and A_ALTCHARSET. These constants, defined in curses.h, can be combined with the C | (or) operator to get multiple attributes. \fIAttrset()\fP sets the current attributes to the given \fIattr\fP; \fIattron()\fP turns on the given \fIattrs\fP in addition to any attributes that are already on; \fIattroff()\fP turns off the given attributes, without affecting any others. \fIstandout()\fP and \fIstandend()\fP are equivalent to \fIattron\fP(A_STANDOUT) and \fIattroff\fP(A_STANDOUT). X.PP Since standout is stored in the 8th bit of the text byte, it is possible to recompile curses so that only 8 bits are stored for each character, making a smaller curses, and still be able to use standout. Also, programs that restrict themselves to the routines \fIstandout()\fP and \fIstandend()\fP will work with both the new and old curses. X.PP If the particular terminal does not have the particular attribute or combination requested, curses will attempt to use some other attribute in its place. If the terminal has no highlighting at all, all attributes will be ignored. X.NH 2 XFunction Keys X.PP Many terminals have special keys, such as arrow keys, keys to erase the screen, insert or delete text, and keys intended for user functions. The particular sequences these terminals send differs from terminal to terminal. Curses allows the programmer to handle these keys. X.PP A program using function keys should turn on the keypad by calling X.DS \fIkeypad\fP(\fBstdscr\fP, TRUE) X.DE at initialization. This will cause special characters to be passed through to the program by the function \fIgetch()\fP. These keys have constants which are defined in curses.h. They have values starting at 0401, so they should not be stored in a \fBchar\fP variable, as significant bits will be lost. X.PP A program using function keys should avoid using the \s-2ESCAPE\s0 key, since most sequences start with escape, creating an ambiguity. Curses will set a one second alarm to deal with this ambiguity, which will cause delayed response to the escape key. It is a good idea to avoid escape in any case, since there is eventually pressure for nearly \fIany\fP screen oriented program to accept arrow key input. X.NH 2 Scrolling Region X.PP There is a user accessible scrolling region, like the DEC VT100. Normally, it is set to the entire window, but the calls X.DS \fIsetscrreg\fP(top, bot) \fIwsetscrreg\fP(win, top, bot) X.DE set the scrolling region for \fBstdscr\fP or the given window to any combination of top and bottom margins. If scrolling has been enabled with \fIscrollok\fP, scrolling will take place only within that window. See the \fICurses Reference Manual\fP for the detailed semantics of this construct. X.NH 2 Mini-Curses\u*\d X.FS \u*\dThis feature is not supported in the current test release. It will be implemented in the official distribution. X.FE X.PP The new curses is bigger than the old one, and has to copy from the current window to an internal screen image for every call to \fIrefresh()\fP. If the programmer is only interested in screen output optimization, and does not want the windowing or input functions, an interface to the lower level routines is available. This will make the program somewhat smaller and faster. The interface is a subset of full curses, so that conversion between the levels is not necessary to switch from mini-curses to full curses. X.PP The subset mainly requires you to avoid use of more than the one window \fBstdscr\fP. Thus, all functions beginning with ``w'' are generally undefined. Certain high level functions that are convenient but not essential are also not available, including \fIprintw()\fP and \fIscanw()\fP Also, the input routine \fIgetch()\fP cannot be used with mini-curses. Features implemented at a low level, such as use of hardware insert/delete line and video attributes, are available in both versions. Also, mode setting routines such as \fIcbreak()\fP and \fInoecho()\fP are allowed. See the manual page for the exact list of routines allowed with mini-curses. X.PP To access mini-curses, add \fB-DMINICURSES\fP to the CFLAGS in your makefile. If you ask for routines that are not in the subset, the loader will print error messages such as X.DS Undefined: no_getch no_waddch X.DE to tell you that the routines \fIgetch()\fP and \fIwaddch()\fP were used but are not available in the subset. Since the preprocessor is involved in the implementation of mini-curses, you must recompile the entire program if you change from one version to the other. Similarly, programs compiled with the old curses must be recompiled for the new curses. X.NH 2 TTY Mode Functions X.PP In addition to the save/restore routines \fIsavetty()\fP and \fIresetty()\fP, standard routines are available for going into and out of normal tty mode. These routines are \fIresetterm()\fP, which puts the terminal back in the mode it was in when curses was started, and \fIfixterm()\fP, which undoes the effects of \fIresetterm()\fP, that is, restores the ``current curses mode''. \fIendwin()\fP automatically calls \fIresetterm()\fP, and the routine to handle control-Z (on 4.1BSD systems with process control) also uses \fIresetterm()\fP and \fIfixterm()\fP. The programmer should use these routines before and after shell escapes, and also if he writes his own routine to handle control-Z. These routines are also available at the \fIterminfo\fP level. X.NH 2 Typeahead Check\u*\d X.FS \u*\dThis feature is not supported in the current test release. It will be implemented in the official distribution. X.FE X.PP On systems that support it (current only 4.1BSD), if the user types something during an update, the update will stop, pending a future update. This is useful when the user rapidly hits several keys, each of which causes a good deal of output. This feature is automatic and cannot be disabled. X.NH 2 Getstr() X.PP The routine \fIgetstr()\fP is smarter. The semantics are slightly different from the old \fIgetstr()\fP, but no incompatibilities are anticipated. No matter what the setting of \fIecho\fP is, strings typed in here are echoed at the current cursor location. The users erase and kill characters are understood and handled. This makes it unnecessary for an interactive program to deal with erase, kill, and echoing when the user is typing a line of text. X.NH 2 Longname() X.PP The function \fIlongname()\fP is now useful and actually works. The previous version required the programmer to call \fItgetent()\fP directly and pass the resulting string, along with a buffer, to \fIlongname()\fP. The string actually returned was the second alias for the terminal, not the long name. X.PP The new \fIlongname()\fP function does not take any arguments. It returns a pointer to a static area containing the actual long name of the terminal. No call to \fItgetent()\fP is needed, in fact, that routine no longer exists. X.NH 2 Nodelay Mode X.PP The call X.DS \fInodelay\fP(\fBstdscr\fP, TRUE) X.DE will put the terminal in ``nodelay mode''. While in this mode, any call to \fIgetch()\fP will return -1 if there is nothing waiting to be read immediately. This is useful for writing programs requiring ``real time'' behavior where the user watches action on the screen and presses a key when he wants something to happen. For example, the cursor can be moving across the screen, and the user can press an arrow key to change direction. This mode is especially useful for games such as PacMan and Space Invaders. X.NH 2 Portability X.PP Several useful routines are provided to enhance portability. While these routines do not directly relate to terminal handling, their implementation is different from system to system, and the differences can be isolated from the user program by including them in curses. X.PP XFunctions \fIerasechar()\fP and \fIkillchar()\fP return the characters which erase one character, and kill the entire input line, respectively. The function \fIbaudrate()\fP will return the current baud rate, as an integer. (For example, at 9600 baud, the integer 9600 will be returned, not the value B9600 from .) The routine \fIflushinp()\fP will cause all typeahead to be thrown away. X.NH 2 XFeatures No Longer Supported X.PP In general, an effort has been made to support old features where possible. However, there are some features of the old curses that cannot be supported, due to the change to terminfo, or due to other miscelaneous causes. X.PP The old curses defined a number of two letter variables, such as CM, containing termcap capabilities. These variables are no longer accessible to the user. In general, their semantics are different, as are their names. A program using primarily these variables is really written at the termcap level. Also unavailable are the related variables NONL, GT, and UPPERCASE. X.PP Such programs should be recoded to avoid these capabilities, if at all possible, instead using the higher level curses functions. If this is not possible, recode at the terminfo level. A program making only light use can probably be easily changed to avoid these variables completely. A program at the terminfo level that only needs motion optimization should probably still be recoded to use the high level routines, in order to work on more terminals. If this is not possible, recode at the terminfo level, continuing to use \fImvcur()\fP, which is still supported. It is not necessary to call \fImvcur()\fP to move to the lower left corner of the screen before calling \fIendwin()\fP. X.PP Some programs (notably rogue) use varibles in which begin with an underline. Use of these variables and fields is to be avoided. Most of the internal structures used by curses are hidden from the user. The variables _tty and _tty_ch are no longer accessible. (Since _tty was a version 7 dependent structure, it was not portable to use it anyway.) Useful fields, such as the erase and kill characters, and the baud rate, can be discovered using the portable functions described above. X.NH Termlib-Level Changes X.PP The termcap(3) (termlib) library has been consolidated with the curses(3) library to form a new curses(3) library. The termlib level is very different in the new version. The routines \fItgetent()\fP, \fItgetnum()\fP, \fItgetstr()\fP, and \fItgetflag()\fP are gone. Initialization is instead done by calling X.DS \fIsetupterm\fP(termtype, filedes, errret) \fBchar\fP *termtype; \fBint\fP filedes; \fBint\fP *errret; X.DE This routine takes care of all reading in of capabilities, and any other system dependent initialization. The terminal type can be passed as 0, causing \fIsetupterm()\fP to use \fIgetenv\fP(``TERM'') as a default. \fIerrret\fP is a pointer to an integer used to return a status value. The value returned is 0 if there is no such terminal type, 1 if all went well, or -1 for some trouble. A null pointer can be passed for this value, telling \fIsetupterm()\fP to print an error message and exit if the terminal cannot be found. X.PP When exiting, or calling a shell escape, the user program should call \fIresetterm()\fP to restore the tty modes. After the shell escape, \fIfixterm()\fP can be called to set the tty modes back to their internal settings. These calls are now \fBrequired\fP, since they perform system dependent processing. They do not output the \fBenter_ca_mode\fP and \fBexit_ca_mode\fP strings (\fBti\fP and \fBte\fP in termcap) but should be called at the same times. \fISetupterm()\fP calls \fIfixterm()\fP. X.PP \fItgoto()\fP has been replaced by \fItparm()\fP, which is a more powerful parameterized string mechanism. The \fItgoto()\fP routine is still available for compatibility. \fItputs()\fP is unchanged. X.PP The external variables \fBUP\fP, \fBBC\fP, \fBPC\fP, and \fBospeed\fP no longer exist. The programmer need not worry about these, as their function is now handled internally. X.NH Changes from Termcap to Terminfo X.PP This section describes the extensions in terminfo that were not present in termcap, and the incompatible changes that were made. It is intended for a programmer or termcap author who is familiar with termcap and wishes to become familiar with terminfo. The emphasis is on the database, not on the programmer interface. X.NH 2 Syntax X.PP The first thing you will notice upon scanning terminfo is that it looks cosmetically different from termcap. All the backslashes are gone from ends of lines. Fields are separated with commas instead of colons, and white space after the commas makes them more readable. Continuation lines are now defined as lines beginning with a blank or tab, not lines following a backslash. These changes make terminfo easier to read and to modify. X.NH 2 Names X.PP The names of the capabilities are no longer limited to two letters. There is no longer a hard limit to the names, but an informal limit of 5 characters is used. Since the two letter limit is gone, many of the capabilities have been renamed. They now correspond as closely as possible the the ANSI standard XX3.64. While learning the new set of names will be tricky at first, eventually life will be simpler, since most new terminals use the ANSI abbreviations. X.NH 2 Defaults X.PP A change that is perhaps not so obvious is that certain defaults are no longer implied. In termcap, \er was assumed to be a carriage return unless \fBnc\fP was present, indicating that it did not work, or \fBcr\fP was present, indicating an alternative. In terminfo, if \fBcr\fP is present, the string so given works, otherwise it should be assumed \fInot\fP to work. The \fBbs\fP and \fBbc\fP capabilities are replaced by \fBcub\fP and \fBcub1\fP. (The former takes a parameter, moving left that many spaces. The latter is probably more common in terminals and moves left one space.) \fBnl\fP (linefeed) has been split into two functions: \fBcud1\fP (moves the cursor down one line) and \fBind\fP (scroll forward). \fBcud1\fP applies when the cursor is not on the bottom line, \fBind\fP applies when it is on the bottom line. The bell capability is now explicitly given as \fBbel\fP. X.NH 2 Compilation X.PP The terminfo database is compiled, unlike termcap. This means that a terminfo source file (describing some set of terminals) is processed by the terminfo compiler, producing a binary description of the terminal in a file under /etc/term. The setupterm routine reads in this file. X.PP The advantage to compilation is that starting up a program using terminfo is faster. It is no longer necessary to carry around the variable TERMCAP in the environment. It is actually faster to start up a compiled terminfo \fIwithout\fP the environment variable, than it is to start up an uncompiled termcap \fIwith\fP the environment variable. The increase in speed comes partly from not having to skip past other terminal descriptions, and partly from the compiler having sorted the capabilities into order so that a linear scan can read them in. (The termcap initialization algorithm is quadratic on the size of the capability. The more capabilities you are interested in, the worse this gets. It had gotten to the point where it took 2 CPU seconds on a VAX 11/750 to start up a process using an uncompiled terminfo!) X.PP There exists an environment variable TERMINFO which is taken by the compiler to be the destination directory of the new object files. It is also used by \fIsetupterm()\fP to find an entry for a given terminal. First it looks in the directory given in TERMINFO and, if not found there, checks /etc/term. \fBNote\fP, however, that, unlike the old TERMCAP variable, you may not put the source for an entry in the TERMINFO variable. \fIAll\fP terminfo entries must be compiled. X.NH 2 Parameterised Strings X.PP The old \fItgoto()\fP mechanism, which was designed for cursor addressing only, has been replaced by a more general parameter mechanism, accessed through the function \fItparm()\fP. Since the parameters are not compatible in the terminfo database, a termcap \fBcm\fI description must be converted manually to terminfo. X.PP The new mechanism is based on a stack. % operations are used to push parameters and constants onto the stack, do arithmetic and other operations on the top of the stack, and print out values in various formats. This makes it possible to handle a larger class of terminals, such as the AED 512, which addresses the cursor in terms of pixels, not character positions, and the TEC scope, which numbers the rows and columns from the lower right hand corner of the screen. Any number of parameters from 1 to 9 is possible, whereas \fItgoto()\fP allowed only two parameters. If-then-else testing is possible, as is storage in a limited number of variables. There is no provision for loops or printing strings in any format other than %s. The full details are described in terminfo(5). X.PP A few brief examples are included here to show common conversions. For more examples, compare the termcap \fBcm\fP and terminfo \fBcup\fP entries for your favorite terminal. ``%+ '' (add space and print as a character) would be treated as ``%p1%' '%+%c'', that is, push the first parameter, push space, add the top two numbers on the stack, and output the top item on the stack using character (%c) format. (Of course, for the second parameter, the %p1 must be changed to %p2.) ``%.'' (print as a character) would be ``%p1%c''. ``%d'' (print in decimal) would be ``%p1%d''. As with \fItgoto()\fP, characters standing by themselves (no % sign) are output as is. X.NH 2 More Capabilities X.PP There are a number of new capabilities. The set of new capabilities may vary, depending on the version of termcap you are used to. It is probably worthwhile to read terminfo(5) for a complete list. This section describes capabilities new to terminfo that were never put in termcap. X.PP There are provisions for dealing with more video attributes. Termcap had strings to turn on and off standout and underline modes. Terminfo has these and several more. There are strings to turn on bold, inverse video, blinking, dim, protected, and blanking. Rather than have separate string for turning off each of these, a single capability: \fBsgr0\fP, turns them all off. X.PP The effect of turning on more than one attribute at a time with the separate strings is undefined. A parameterized string, \fBsgr\fP, can be used to turn them on in combination. X.PP More function keys are defined now. There are provisions for f0 through f10 as well as keys such as erase, insert mode, insert line, delete line, delete character, print, and so on. All of these keys can be accessed through curses as if they were single characters. Also, \fBvi\fP version 3.8 has default meanings for many of them. X.PP Several new uses are made of parameterized strings. For example, capabilities exist to move the cursor to a particular column in the current row, a particular row in the current column, and to move left, right, up, or down a given number of spaces. These capabilities make a big difference on some terminals, such as the Tektronix 4025. Also, column addressing is useful for filters that do not know what row they are in, or as a shorter form of cursor addressing when the target is in the same row. X.PP There are now capabilities to turn on and off a local printer, and to print the current page. Also, there are provisions for moving the cursor to and from a status line. These capabilities can be used by a background status program, such as \fIsysline\fP, to keep status information in the status line without bothering foreground processes. This only works on terminals with a writable status line, such as the h19 or tvi950, or on terminals where one can be simulated, such as the hp2626, vt100, or ambassador, by allocating one of the ordinary screen lines for a status line. X.NH 2 How to Convert from Termcap to Terminfo X.PP This section is intended for programmers who need to convert programs that use termcap to the new terminfo database. It describes the steps needed for the conversion. X.PP If you must make the conversion, you are strongly urged to convert to curses, rather than converting to terminfo. The curses interface is higher level and will probably do a better job of optimizing your output. Your program will work on a wider range of terminals if you use curses. It will also become more portable. The effort to convert to curses is probably about the same as to convert to terminfo. X.PP There are some programs for which curses is not a possibility. Curses takes over the CRT screen, and this implies initially clearing the screen. For some programs, such as filters, this may not make sense. Also, if you are writing a special purpose program which uses some terminfo capability that curses does not use, it will probably be necessary to use the terminfo level interface. X.NH 2 Conversion X.PP The first step is to include the headers and (in that order). These headers will bring into existence a set of ``variables'' (actually macros) that contain values of capabilities. For example, the macro \fBcursor_address\fP will be defined, replacing the termcap \fBcm\fP capability. You should remove the declarations for all variables you use for capabilities returned by \fItgetflag()\fP, \fItgetnum()\fP, and \fItgetstr()\fP. X.PP The most difficult step is that all variables removed in the previous step must be renamed the standard names. For example, if you stored \fBcm\fP in the variable CM, you would change \fItputs\fP(\fItgoto\fP(\fBCM\fP, i, j), 1, outch) to \fItputs\fP(\fItgoto\fP(\fBcursor_address\fP, i, j), 1, outch). Consult terminfo(5) for a list of standard names. A \fBsed\fP script is often useful for this step. Care must be taken to avoid mention of the variable as part of a longer word (a version of \fBsed\fP supporting the \fBex\fP \ convention is useful here.) Also, you should proofread the results, since sometimes comments and strings get substituted that shouldn't have been. X.PP Remove all your termcap initialization code. This code typically calls \fItgetent()\fP, \fItgetstr()\fP, \fItgetflag()\fP, and \fItgetnum()\fP. You can also remove declarations used only for this initialization, usually including buffers for the entry and string values. Replace it with a single call to \fIsetupterm\fP(0, 1, 0). This call will never return if something goes wrong, that is, if there is no $TERM in the environment or there is no such terminal, the routine will print an error and exit. If you need an error indication passed back for more sophisticated error recovery, pass an integer variable in the third parameter, i.e. setupterm(0, 1, &i). The value returned in \fBi\fP will be the same as that previously returned by \fItgetent()\fP. Other more sophisticated calls to \fIsetupterm()\fP are possible, see the documentation if some terminal other than $TERM or some file descriptor other than \fBstdout\fP are involved. X.PP Before the program exits, insert a call to \fIresetterm()\fP. This will restore the tty modes to their state before setupterm was called, and do any other system dependent exit processing. This routine can also be called before a shell escape, you should call \fIfixterm()\fP after the shell escape to restore the tty modes to those needed by terminfo. (Currently \fIsetupterm()\fP will turn off the XXTABS bit in the tty driver, since some terminals need to send control I for escape sequences. You should be sure to expand any tabs in your software if necessary.) X.PP XFrom the programmers viewpoint, the routine \fItputs()\fP is exactly as in termcap. The padding syntax in the capability is different, but this only affects the capabilities in the terminfo database. No change to a program will be needed for \fItputs()\fP. X.PP The \fItgoto()\fP routine is kept around for upward compatibility, but you should probably replace calls to \fItgoto()\fP by calls to \fItparm()\fP. The call \fItgoto\fP(cap, y, x) will call \fItparm\fP(cap, x, y). Note that the order of the last two arguments is reversed - it was backwards in \fItgoto()\fP from what it probably should have been. In addition to the capability, \fItparm()\fP can now take up to nine parameters, or as few as one. X.PP If you use certain capabilities, there are a few convention changes you should be aware of. These do not affect very many programs, but will require some minor recoding of a few programs. In termcap, the cursor is moved left by control-H if \fBbs\fP is present, otherwise, if \fBbc\fP is present, that character is used. In terminfo, the cursor is moved left with \fBcub1\fP, if present, or by \fBcub\fP, if present. If neither is there, there is no implied control-H. Similarly, termcap assumed that control-M was carriage return unless \fBnc\fP or \fBcr\fP was specified. In terminfo, carriage return is always the string specified by \fBcr\fP, and if not present, there is no carriage return capability. In termcap, linefeed is assumed to both move the cursor down (if it is not on the bottom line) and to scroll one line (if it is on the bottom line), unless \fBns\fP is present. \fBsf\fP and \fBdo\fP capabilities were present but little used, and some software assumed that \fBsf\fP worked with the cursor anywhere on the screen. In terminfo, there is no implied linefeed - moving the cursor down is done with \fBcud1\fP or \fBcud\fP and scrolling is done with \fBind\fP. \fBind\fP is only defined when the cursor is at the bottom of the screen. Finally, the implied control G used to ring the bell unless \fBvb\fP was present has been replaced with an explicit \fBbel\fP. X.PP Replace references in your makefile from -ltermcap or -ltermlib with references to -lcurses. X.PP Now recompile your program. It should run properly using terminfo. X.NH 2 Space Conditions X.PP The expansion of a macro name into a structure reference will probably make your program a bit bigger. If space is a problem, one thing you can do is add \fB-DSINGLE\fP to the CFLAGS in your makefile. This causes the macros to expand to a static reference instead of a dynamic reference, resulting in smaller code. It cannot be used if you intend to involve more than one terminal from a single process. Since very few programs talk to two terminals at once, it is almost always safe to define SINGLE. X.PP If your program was pushing the limit on a small machine, it may not fit with terminfo unless you trim it down some. While the startup routines are faster, they tend to generate larger code than those of termcap. Also, \fItputs()\fP and \fItparm()\fP are more sophisticated and larger. //go.sysin dd * echo 'x - =doc/compile.1' sed 's/^X//' <<'//go.sysin dd *' >=doc/compile.1 X.TH COMPILE 1 Terminfo/Curses X.SH NAME compile \- Compile the terminfo database X.SH SYNOPSIS X.B /etc/term/compile [\fB-v\fR[\fIn\fR]] source-file X.SH DESCRIPTION X.I Compile is the program which translates the source files in the terminfo terminal capability database into their object format. The given X.I file is expected to contain one or more terminfo entries, as described in X.IR terminfo (5). This file is expected to be self-contained, i.e., it may not contain ``\fBuse\fP'' entries which refer to terminals not described fully in the same file. X.PP The object files are normally placed in subdirectories of the directory X/etc/term (see X.IR term (5)), but if the environment variable TERMINFO is defined, it is taken to be the name of an alternate directory to use. X.PP Debugging and tracing information may be obtained by use of the X.B -v flag. The number after the flag controls the amount of debugging information given, according to the following table: X.IP 1 Names of files created and linked X.IP 2 Information related to the ``\fBuse\fR'' facility X.IP 3 Statistics from the hashing algorithm X.IP 5 String-table memory allocations X.IP 7 Entries into the string-table X.IP 8 List of tokens encountered by scanner X.IP 9 All values computed in construction of the hash table X.in -0.5i X.sp If \fIn\fP is not given, it is taken to be one. X.SH FILES X/etc/term/* Default location of object files X.SH SEE ALSO terminfo(5), term(5), dump(1). X.SH AUTHOR Pavel Curtis, Cornell University X.br (decvax!cornell!pavel or Pavel.Cornell@Udel-Relay) X.SH BUGS You tell me. //go.sysin dd * echo 'x - =doc/dump.1' sed 's/^X//' <<'//go.sysin dd *' >=doc/dump.1 X.TH DUMP 1 Terminfo/Curses X.SH NAME dump \- Print the contents of a compiled terminfo file in human-readable form X.SH SYNOPSIS X.B /etc/term/dump file ... X.SH DESCRIPTION X.I Dump reads the given files and decodes their contents to derive a reasonable representation of the terminfo entry which produced the file originally. It should be noted, in case of emergency, that the output of X.I dump is perfectly usable as the input to X.IR compile (1). X.SH SEE ALSO compile(1), term(5), terminfo(5) X.SH AUTHOR Pavel Curtis, Cornell University X.br (decvax!cornell!pavel or Pavel.Cornell@Udel-Relay) //go.sysin dd * exit