- [listed in <B><A HREF="terminfo.5.html">terminfo(5)</A></B>]. The <B>terminfo</B> variables <B>lines</B> and
- <B>columns</B> are initialized by <B>setupterm</B> as follows: If
- <B>use_env(FALSE)</B> has been called, values for <B>lines</B> and
- <B>columns</B> specified in <B>terminfo</B> are used. Otherwise, if the
- environment variables <B>LINES</B> and <B>COLUMNS</B> exist, their val-
- ues are used. If these environment variables do not exist
- and the program is running in a window, the current window
- size is used. Otherwise, if the environment variables do
- not exist, the values for <B>lines</B> and <B>columns</B> specified in
- the <B>terminfo</B> database are used.
-
- The header files <B>curses.h</B> and <B>term.h</B> should be included
- (in this order) to get the definitions for these strings,
- numbers, and flags. Parameterized strings should be
- passed through <B>tparm</B> to instantiate them. All <B>terminfo</B>
- strings [including the output of <B>tparm</B>] should be printed
- with <B>tputs</B> or <B>putp</B>. Call the <B>reset_shell_mode</B> to restore
- the tty modes before exiting [see <B><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></B>].
- Programs which use cursor addressing should output
- <B>enter_ca_mode</B> upon startup and should output <B>exit_ca_mode</B>
- before exiting. Programs desiring shell escapes should
- call
-
- <B>reset_shell_mode</B> and output <B>exit_ca_mode</B> before the shell
- is called and should output <B>enter_ca_mode</B> and call
- <B>reset_prog_mode</B> after returning from the shell.
-
- The <B>setupterm</B> routine reads in the <B>terminfo</B> database, ini-
- tializing the <B>terminfo</B> structures, but does not set up the
- output virtualization structures used by <B>curses</B>. The ter-
- minal type is the character string <I>term</I>; if <I>term</I> is null,
- the environment variable <B>TERM</B> is used. All output is to
- file descriptor <B>fildes</B> which is initialized for output.
- If <I>errret</I> is not null, then <B>setupterm</B> returns <B>OK</B> or <B>ERR</B>
- and stores a status value in the integer pointed to by
- <I>errret</I>. A return value of <B>OK</B> combined with status of <B>1</B> in
- <I>errret</I> is normal. If <B>ERR</B> is returned, examine <I>errret</I>:
-
- <B>1</B> means that the terminal is hardcopy, cannot be
- used for curses applications.
-
- <B>0</B> means that the terminal could not be found, or
- that it is a generic type, having too little
- information for curses applications to run.
-
- <B>-1</B> means that the <B>terminfo</B> database could not be
- found.
-
- If <I>errret</I> is null, <B>setupterm</B> prints an error message upon
- finding an error and exits. Thus, the simplest call is:
-
- <B>setupterm((char</B> <B>*)0,</B> <B>1,</B> <B>(int</B> <B>*)0);</B>,
-
- which uses all the defaults and sends the output to <B>std-</B>
- <B>out</B>.
-
- The <B>setterm</B> routine is being replaced by <B>setupterm</B>. The
- call:
-
- <B>setupterm(</B><I>term</I><B>,</B> <B>1,</B> <B>(int</B> <B>*)0)</B>
-
- provides the same functionality as <B>setterm(</B><I>term</I><B>)</B>. The
- <B>setterm</B> routine is included here for BSD compatibility,
- and is not recommended for new programs.
-
- The <B>set_curterm</B> routine sets the variable <B>cur_term</B> to
- <I>nterm</I>, and makes all of the <B>terminfo</B> boolean, numeric, and
- string variables use the values from <I>nterm</I>. It returns
- the old value of <B>cur_term</B>.
-
- The <B>del_curterm</B> routine frees the space pointed to by
- <I>oterm</I> and makes it available for further use. If <I>oterm</I> is
- the same as <B>cur_term</B>, references to any of the <B>terminfo</B>
- boolean, numeric, and string variables thereafter may
- refer to invalid memory locations until another <B>setupterm</B>
- has been called.
-
- The <B>restartterm</B> routine is similar to <B>setupterm</B> and
- <B>initscr</B>, except that it is called after restoring memory
- to a previous state (for example, when reloading a game
- saved as a core image dump). It assumes that the windows
- and the input and output options are the same as when mem-
- ory was saved, but the terminal type and baud rate may be
- different. Accordingly, it saves various tty state bits,
- does a setupterm, and then restores the bits.
-
- The <B>tparm</B> routine instantiates the string <I>str</I> with parame-
- ters <I>pi</I>. A pointer is returned to the result of <I>str</I> with
- the parameters applied.
-
- The <B>tputs</B> routine applies padding information to the
- string <I>str</I> and outputs it. The <I>str</I> must be a terminfo
- string variable or the return value from <B>tparm</B>, <B>tgetstr</B>,
- or <B>tgoto</B>. <I>affcnt</I> is the number of lines affected, or 1 if
- not applicable. <I>putc</I> is a <B>putchar</B>-like routine to which
- the characters are passed, one at a time.
-
- The <B>putp</B> routine calls <B>tputs(</B><I>str</I><B>,</B> <B>1,</B> <B>putchar)</B>. Note that
- the output of <B>putp</B> always goes to <B>stdout</B>, not to the
- <I>fildes</I> specified in <B>setupterm</B>.
-
- The <B>vidputs</B> routine displays the string on the terminal in
- the video attribute mode <I>attrs</I>, which is any combination
- of the attributes listed in <B><A HREF="ncurses.3x.html">curses(3x)</A></B>. The characters
- are passed to the <B>putchar</B>-like routine <I>putc</I>.
-
- The <B>vidattr</B> routine is like the <B>vidputs</B> routine, except
- that it outputs through <B>putchar</B>.
-
- The <B>mvcur</B> routine provides low-level cursor motion. It
- takes effect immediately (rather than at the next
- refresh).
-
- The <B>tigetflag</B>, <B>tigetnum</B> and <B>tigetstr</B> routines return the
- value of the capability corresponding to the <B>terminfo</B> <I>cap-</I>
- <I>name</I> passed to them, such as <B>xenl</B>.
-
- The <B>tigetflag</B> routine returns the value <B>-1</B> if <I>capname</I> is
- not a boolean capability, or <B>0</B> if it is canceled or absent
- from the terminal description.