- provides the same functionality as <STRONG>setterm(</STRONG><EM>term</EM><STRONG>)</STRONG>. The
- <STRONG>setterm</STRONG> routine is included here for BSD compatibility,
- and is not recommended for new programs.
-
- The <STRONG>set_curterm</STRONG> routine sets the variable <STRONG>cur_term</STRONG> to
- <EM>nterm</EM>, and makes all of the <STRONG>terminfo</STRONG> boolean, numeric, and
- string variables use the values from <EM>nterm</EM>. It returns
- the old value of <STRONG>cur_term</STRONG>.
-
- The <STRONG>del_curterm</STRONG> routine frees the space pointed to by
- <EM>oterm</EM> and makes it available for further use. If <EM>oterm</EM> is
- the same as <STRONG>cur_term</STRONG>, references to any of the <STRONG>terminfo</STRONG>
- boolean, numeric, and string variables thereafter may re-
- fer to invalid memory locations until another <STRONG>setupterm</STRONG>
- has been called.
-
- The <STRONG>restartterm</STRONG> routine is similar to <STRONG>setupterm</STRONG> and
- <STRONG>initscr</STRONG>, 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,
+</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
+ These low-level routines must be called by programs that have to deal
+ directly with the <STRONG>terminfo</STRONG> database to handle certain terminal capabil-
+ ities, such as programming function keys. For all other functionality,
+ <STRONG>curses</STRONG> routines are more suitable and their use is recommended.
+
+ None of these functions use (or are aware of) multibyte character
+ strings such as UTF-8:
+
+ <STRONG>o</STRONG> capability names use the POSIX portable character set
+
+ <STRONG>o</STRONG> capability string values have no associated encoding; they are
+ strings of 8-bit characters.
+
+
+</PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
+ Initially, <STRONG>setupterm</STRONG> should be called. The high-level curses functions
+ <STRONG>initscr</STRONG> and <STRONG>newterm</STRONG> call <STRONG>setupterm</STRONG> to initialize the low-level set of
+ terminal-dependent variables [listed in <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>].
+
+ Applications can use the terminal capabilities either directly (via
+ header definitions), or by special functions. The header files <STRONG>curs-</STRONG>
+ <STRONG>es.h</STRONG> and <STRONG>term.h</STRONG> should be included (in this order) to get the defini-
+ tions for these strings, numbers, and flags.
+
+ The <STRONG>terminfo</STRONG> variables <STRONG>lines</STRONG> and <STRONG>columns</STRONG> are initialized by <STRONG>setupterm</STRONG>
+ as follows:
+
+ <STRONG>o</STRONG> If <STRONG>use_env(FALSE)</STRONG> has been called, values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG>
+ specified in <STRONG>terminfo</STRONG> are used.
+
+ <STRONG>o</STRONG> Otherwise, if the environment variables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> exist,
+ their values 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 <STRONG>lines</STRONG> and <STRONG>columns</STRONG> specified in the <STRONG>terminfo</STRONG> database are
+ used.
+
+ Parameterized strings should be passed through <STRONG>tparm</STRONG> to instantiate
+ them. All <STRONG>terminfo</STRONG> strings (including the output of <STRONG>tparm</STRONG>) should be
+ printed with <STRONG>tputs</STRONG> or <STRONG>putp</STRONG>. Call <STRONG>reset_shell_mode</STRONG> to restore the tty
+ modes before exiting [see <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>].
+
+ Programs which use cursor addressing should
+
+ <STRONG>o</STRONG> output <STRONG>enter_ca_mode</STRONG> upon startup and
+
+ <STRONG>o</STRONG> output <STRONG>exit_ca_mode</STRONG> before exiting.
+
+ Programs which execute shell subprocesses should
+
+ <STRONG>o</STRONG> call <STRONG>reset_shell_mode</STRONG> and output <STRONG>exit_ca_mode</STRONG> before the shell is
+ called and
+
+ <STRONG>o</STRONG> output <STRONG>enter_ca_mode</STRONG> and call <STRONG>reset_prog_mode</STRONG> after returning from
+ the shell.
+
+ The <STRONG>setupterm</STRONG> routine reads in the <STRONG>terminfo</STRONG> database, initializing the
+ <STRONG>terminfo</STRONG> structures, but does not set up the output virtualization
+ structures used by <STRONG>curses</STRONG>. These are its parameters:
+
+ <EM>term</EM> is the terminal type, a character string. If <EM>term</EM> is null, the
+ environment variable <STRONG>TERM</STRONG> is used.
+
+ <EM>filedes</EM>
+ is the file descriptor used for all output.
+
+ <EM>errret</EM>
+ points to an optional location where an error status can be re-
+ turned to the caller. If <EM>errret</EM> is not null, then <STRONG>setupterm</STRONG>
+ returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG> and stores a status value in the integer
+ pointed to by <EM>errret</EM>. A return value of <STRONG>OK</STRONG> combined with sta-
+ tus of <STRONG>1</STRONG> in <EM>errret</EM> is normal.
+
+ If <STRONG>ERR</STRONG> is returned, examine <EM>errret</EM>:
+
+ <STRONG>1</STRONG> means that the terminal is hardcopy, cannot be used for
+ curses applications.
+
+ <STRONG>setupterm</STRONG> determines if the entry is a hardcopy type by
+ checking the <STRONG>hc</STRONG> (<STRONG>hardcopy</STRONG>) capability.
+
+ <STRONG>0</STRONG> means that the terminal could not be found, or that it is
+ a generic type, having too little information for curses
+ applications to run.
+
+ <STRONG>setupterm</STRONG> determines if the entry is a generic type by
+ checking the <STRONG>gn</STRONG> (<STRONG>generic</STRONG>) capability.
+
+ <STRONG>-1</STRONG> means that the <STRONG>terminfo</STRONG> database could not be found.
+
+ If <EM>errret</EM> is null, <STRONG>setupterm</STRONG> prints an error message upon find-
+ ing an error and exits. Thus, the simplest call is:
+
+ <STRONG>setupterm((char</STRONG> <STRONG>*)0,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0);</STRONG>,
+
+ which uses all the defaults and sends the output to <STRONG>stdout</STRONG>.
+
+
+</PRE><H3><a name="h3-The-Terminal-State">The Terminal State</a></H3><PRE>
+ The <STRONG>setupterm</STRONG> routine stores its information about the terminal in a
+ <STRONG>TERMINAL</STRONG> structure pointed to by the global variable <STRONG>cur_term</STRONG>. If it
+ detects an error, or decides that the terminal is unsuitable (hardcopy
+ or generic), it discards this information, making it not available to
+ applications.
+
+ If <STRONG>setupterm</STRONG> is called repeatedly for the same terminal type, it will
+ reuse the information. It maintains only one copy of a given termi-
+ nal's capabilities in memory. If it is called for different terminal
+ types, <STRONG>setupterm</STRONG> allocates new storage for each set of terminal capa-
+ bilities.
+
+ The <STRONG>set_curterm</STRONG> routine sets <STRONG>cur_term</STRONG> to <EM>nterm</EM>, and makes all of the
+ <STRONG>terminfo</STRONG> boolean, numeric, and string variables use the values from
+ <EM>nterm</EM>. It returns the old value of <STRONG>cur_term</STRONG>.
+
+ The <STRONG>del_curterm</STRONG> routine frees the space pointed to by <EM>oterm</EM> and makes
+ it available for further use. If <EM>oterm</EM> is the same as <STRONG>cur_term</STRONG>, refer-
+ ences to any of the <STRONG>terminfo</STRONG> boolean, numeric, and string variables
+ thereafter may refer to invalid memory locations until another <STRONG>se-</STRONG>
+ <STRONG>tupterm</STRONG> has been called.
+
+ The <STRONG>restartterm</STRONG> routine is similar to <STRONG>setupterm</STRONG> and <STRONG>initscr</STRONG>, except
+ that it is called after restoring memory to a previous state (for exam-
+ ple, when reloading a game saved as a core image dump). <STRONG>restartterm</STRONG>
+ assumes that the windows and the input and output options are the same
+ as when memory was saved, but the terminal type and baud rate may be
+ different. Accordingly, <STRONG>restartterm</STRONG> saves various tty state bits,