- If configured to use the terminal-driver, e.g., for the
- MinGW port,
-
- <STRONG>o</STRONG> <STRONG>setupterm</STRONG> interprets a missing/empty TERM variable as
- the special value "unknown".
-
- <STRONG>o</STRONG> <STRONG>setupterm</STRONG> allows explicit use of the the windows con-
- sole driver by checking if $TERM is set to "#win32con"
- or an abbreviation of that string.
-
- Older versions of <STRONG>ncurses</STRONG> assumed that the file descriptor
- passed to <STRONG>setupterm</STRONG> from <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> uses buffered
- I/O, and would write to the corresponding stream. In ad-
- dition to the limitation that the terminal was left in
- block-buffered mode on exit (like SystemV curses), it was
- problematic because <STRONG>ncurses</STRONG> did not allow a reliable way
- to cleanup on receiving SIGTSTP. The current version uses
- output buffers managed directly by <STRONG>ncurses</STRONG>. Some of the
- low-level functions described in this manual page write to
- the standard output. They are not signal-safe. The high-
- level functions in <STRONG>ncurses</STRONG> use alternate versions of these
- functions using the more reliable buffering scheme.
-
- In System V Release 4, <STRONG>set_curterm</STRONG> has an <STRONG>int</STRONG> return type
- and returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG>. We have chosen to implement the
- X/Open Curses semantics.
-
- In System V Release 4, the third argument of <STRONG>tputs</STRONG> has the
- type <STRONG>int</STRONG> <STRONG>(*putc)(char)</STRONG>.
-
- At least one implementation of X/Open Curses (Solaris) re-
- turns a value other than OK/ERR from <STRONG>tputs</STRONG>. That returns
- the length of the string, and does no error-checking.
-
- X/Open Curses prototypes <STRONG>tparm</STRONG> with a fixed number of pa-
- rameters, rather than a variable argument list. This im-
- plementation uses a variable argument list, but can be
- configured to use the fixed-parameter list. Portable ap-
- plications should provide 9 parameters after the format;
- zeroes are fine for this purpose.
-
- In response to comments by Thomas E. Dickey, X/Open Curses
- Issue 7 proposed the <STRONG>tiparm</STRONG> function in mid-2009.
-
- X/Open notes that after calling <STRONG>mvcur</STRONG>, the curses state
- may not match the actual terminal state, and that an ap-
- plication should touch and refresh the window before re-
- suming normal curses calls. Both <STRONG>ncurses</STRONG> and System V Re-
- lease 4 curses implement <STRONG>mvcur</STRONG> using the SCREEN data allo-
- cated in either <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>. So though it is docu-
- mented as a terminfo function, <STRONG>mvcur</STRONG> is really a curses
- function which is not well specified.
-
- X/Open states that the old location must be given for
- <STRONG>mvcur</STRONG>. This implementation allows the caller to use -1's
- for the old ordinates. In that case, the old location is
- unknown.
-
- Other implementions may not declare the capability name
- arrays. Some provide them without declaring them. X/Open
- does not specify them.
-
- Extended terminal capability names, e.g., as defined by
- <STRONG>tic</STRONG> <STRONG>-x</STRONG>, are not stored in the arrays described here.
+</PRE><H3><a name="h3-Legacy-Data">Legacy Data</a></H3><PRE>
+ <STRONG>setupterm</STRONG> copies the terminal name to the array <STRONG>ttytype</STRONG>. This is not
+ part of X/Open Curses, but is assumed by some applications.
+
+ Other implementions may not declare the capability name arrays. Some
+ provide them without declaring them. X/Open Curses does not specify
+ them.
+
+ Extended terminal capability names, as defined by "<STRONG>tic</STRONG> <STRONG>-x</STRONG>", are not
+ stored in the arrays described here.
+
+
+</PRE><H3><a name="h3-Output-Buffering">Output Buffering</a></H3><PRE>
+ Older versions of <EM>ncurses</EM> assumed that the file descriptor passed to
+ <STRONG>setupterm</STRONG> from <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> uses buffered I/O, and would write to
+ the corresponding stream. In addition to the limitation that the
+ terminal was left in block-buffered mode on exit (like System V
+ <EM>curses</EM>), it was problematic because <EM>ncurses</EM> did not allow a reliable
+ way to clean up on receiving <STRONG>SIGTSTP</STRONG>.
+
+ The current version (ncurses6) uses output buffers managed directly by
+ <EM>ncurses</EM>. Some of the low-level functions described in this manual page
+ write to the standard output. They are not signal-safe. The high-
+ level functions in <EM>ncurses</EM> employ alternate versions of these functions
+ using the more reliable buffering scheme.
+
+
+</PRE><H3><a name="h3-Function-Prototypes">Function Prototypes</a></H3><PRE>
+ The X/Open Curses prototypes are based on the SVr4 <EM>curses</EM> header
+ declarations, which were defined at the same time the C language was
+ first standardized in the late 1980s.
+
+ <STRONG>o</STRONG> X/Open Curses uses <EM>const</EM> less effectively than a later design
+ might, sometimes applying it needlessly to values that are already
+ constant, and in most cases overlooking parameters that normally
+ would use <EM>const</EM>. Passing <EM>const</EM>-qualified parameters to functions
+ that do not declare them <EM>const</EM> may prevent the program from
+ compiling. On the other hand, "writable strings" are an
+ obsolescent feature.
+
+ As an extension, this implementation can be configured to change
+ the function prototypes to use the <EM>const</EM> keyword. The <EM>ncurses</EM> ABI
+ 6 enables this feature by default.
+
+ <STRONG>o</STRONG> X/Open Curses prototypes <STRONG>tparm</STRONG> with a fixed number of parameters,
+ rather than a variable argument list.
+
+ This implementation uses a variable argument list, but can be
+ configured to use the fixed-parameter list. Portable applications
+ should provide nine parameters after the format; zeroes are fine
+ for this purpose.
+
+ In response to review comments by Thomas E. Dickey, X/Open Curses
+ Issue 7 proposed the <STRONG>tiparm</STRONG> function in mid-2009.
+
+ While <STRONG>tiparm</STRONG> is always provided in <EM>ncurses</EM>, the older form is only
+ available as a build-time configuration option. If not specially
+ configured, <STRONG>tparm</STRONG> is the same as <STRONG>tiparm</STRONG>.
+
+ Both forms of <STRONG>tparm</STRONG> have drawbacks:
+
+ <STRONG>o</STRONG> Most of the calls to <STRONG>tparm</STRONG> use only one or two parameters. Passing
+ nine on each call is awkward.
+
+ Using <EM>long</EM> for the numeric parameter type is a workaround to make
+ the parameter use the same amount of stack as a pointer. That
+ approach dates back to the mid-1980s, before C was standardized.
+ Since then, there is a standard (and pointers are not required to
+ fit in a <EM>long</EM>).
+
+ <STRONG>o</STRONG> Providing the right number of parameters for a variadic function
+ such as <STRONG>tiparm</STRONG> can be a problem, in particular for string
+ parameters. However, only a few <EM>terminfo</EM> capabilities use string
+ parameters (for instance, the ones used for programmable function
+ keys).
+
+ The <EM>ncurses</EM> library checks usage of these capabilities, and returns
+ an error if the capability mishandles string parameters. But it
+ cannot check if a calling program provides strings in the right
+ places for the <STRONG>tparm</STRONG> calls.
+
+ The <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG> program checks its use of these capabilities with a
+ table, so that it calls <STRONG>tparm</STRONG> correctly.
+
+ <STRONG>Special</STRONG> <EM>TERM</EM> <STRONG>treatment</STRONG>
+ If configured to use the terminal driver, as with the MinGW port,
+
+ <STRONG>o</STRONG> <STRONG>setupterm</STRONG> interprets a missing/empty <EM>TERM</EM> variable as the special
+ value "unknown".
+
+ SVr4 <EM>curses</EM> uses the special value "dumb".
+
+ The difference between the two is that the former uses the
+ <STRONG>generic_type</STRONG> (<STRONG>gn</STRONG>) <EM>terminfo</EM> capability, while the latter does not.
+ A generic terminal is unsuitable for full-screen applications.
+
+ <STRONG>o</STRONG> <STRONG>setupterm</STRONG> allows explicit use of the the windows console driver by
+ checking if <STRONG>$TERM</STRONG> is set to "#win32con" or an abbreviation of that
+ string.
+
+
+</PRE><H3><a name="h3-Other-Portability-Issues">Other Portability Issues</a></H3><PRE>
+ In SVr4, <STRONG>set_curterm</STRONG> returns an <EM>int</EM>, <STRONG>OK</STRONG> or <STRONG>ERR</STRONG>. We have chosen to
+ implement the X/Open Curses semantics.
+
+ In SVr4, the third argument of <STRONG>tputs</STRONG> has the type "<STRONG>int</STRONG> <STRONG>(*putc)(char)</STRONG>".
+
+ At least one implementation of X/Open Curses (Solaris) returns a value
+ other than <STRONG>OK</STRONG> or <STRONG>ERR</STRONG> from <STRONG>tputs</STRONG>. It instead returns the length of the
+ string, and does no error checking.
+
+ X/Open Curses notes that after calling <STRONG>mvcur</STRONG>, the <EM>curses</EM> state may not
+ match the actual terminal state, and that an application should touch
+ and refresh the window before resuming normal <EM>curses</EM> calls. Both
+ <EM>ncurses</EM> and SVr4 <EM>curses</EM> implement <STRONG>mvcur</STRONG> using the <EM>SCREEN</EM> data allocated
+ in either <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>. So though it is documented as a <EM>terminfo</EM>
+ function, <STRONG>mvcur</STRONG> is really a <EM>curses</EM> function that is not well specified.
+
+ X/Open Curses states that the old location must be given for <STRONG>mvcur</STRONG> to
+ accommodate terminals that lack absolute cursor positioning. <EM>ncurses</EM>
+ allows the caller to use -1 for either or both old coordinates. The -1
+ tells <EM>ncurses</EM> that the old location is unknown, and that it must use
+ only absolute motion, as with the <STRONG>cursor_address</STRONG> (<STRONG>cup</STRONG>) capability,
+ rather than the least costly combination of absolute and relative
+ motion.
+
+
+</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
+ SVr2 (1984) introduced the <EM>terminfo</EM> feature. Its programming manual
+ mentioned the following low-level functions.
+
+ <STRONG>Function</STRONG> <STRONG>Description</STRONG>
+ ------------------------------------------------------------------------
+ <STRONG>fixterm</STRONG> restore terminal to "in <EM>curses</EM>" state
+ <STRONG>gettmode</STRONG> establish current terminal modes
+ <STRONG>mvcur</STRONG> low level cursor motion
+ <STRONG>putp</STRONG> use <STRONG>tputs</STRONG> to send characters via <EM>putchar</EM>
+ <STRONG>resetterm</STRONG> set terminal modes to "out of <EM>curses</EM>" state
+
+ <STRONG>resetty</STRONG> reset terminal flags to stored value
+ <STRONG>saveterm</STRONG> save current modes as "in <EM>curses</EM>" state
+ <STRONG>savetty</STRONG> store current terminal flags
+ <STRONG>setterm</STRONG> establish terminal with given type
+ <STRONG>setupterm</STRONG> establish terminal with given type
+ <STRONG>tparm</STRONG> interpolate parameters into string capability
+ <STRONG>tputs</STRONG> apply padding information to a string
+ <STRONG>vidattr</STRONG> like <STRONG>vidputs</STRONG>, but output through <EM>putchar</EM>
+ <STRONG>vidputs</STRONG> write string to terminal, applying specified attributes
+
+ The programming manual also mentioned functions provided for <EM>termcap</EM>
+ compatibility (commenting that they "may go away at a later date").
+
+ <STRONG>Function</STRONG> <STRONG>Description</STRONG>
+ ------------------------------------------------------------------------
+ <STRONG>tgetent</STRONG> look up <EM>termcap</EM> entry for given <EM>name</EM>
+ <STRONG>tgetflag</STRONG> get Boolean entry for given <EM>id</EM>
+ <STRONG>tgetnum</STRONG> get numeric entry for given <EM>id</EM>
+ <STRONG>tgetstr</STRONG> get string entry for given <EM>id</EM>
+ <STRONG>tgoto</STRONG> apply parameters to given capability
+ <STRONG>tputs</STRONG> write characters via a function parameter, applying padding
+
+ Early <EM>terminfo</EM> programs obtained capability values from the <EM>TERMINAL</EM>
+ structure initialized by <STRONG>setupterm</STRONG>.
+
+ SVr3 (1987) extended <EM>terminfo</EM> by adding functions to retrieve
+ capability values (like the <EM>termcap</EM> interface), and reusing <STRONG>tgoto</STRONG> and
+ <STRONG>tputs</STRONG>.
+
+ <STRONG>Function</STRONG> <STRONG>Description</STRONG>
+ ------------------------------------------------------------------------
+ <STRONG>tigetflag</STRONG> get Boolean entry for given <EM>id</EM>
+ <STRONG>tigetnum</STRONG> get numeric entry for given <EM>id</EM>
+ <STRONG>tigetstr</STRONG> get string entry for given <EM>id</EM>
+
+ SVr3 also replaced several of the SVr2 <EM>terminfo</EM> functions that had no
+ counterpart in the <EM>termcap</EM> interface, documenting them as obsolete.
+
+ <STRONG>Function</STRONG> <STRONG>Replaced</STRONG> <STRONG>by</STRONG>
+ ------------------------------------------------------------------------
+ crmode cbreak
+ fixterm reset_prog_mode
+ gettmode <EM>n/a</EM>
+ nocrmode nocbreak
+ resetterm reset_shell_mode
+ saveterm def_prog_mode
+ setterm setupterm
+
+ SVr3 kept the <STRONG>mvcur</STRONG>, <STRONG>vidattr</STRONG>, and <STRONG>vidputs</STRONG> functions, along with <STRONG>putp</STRONG>,
+ <STRONG>tparm</STRONG>, and <STRONG>tputs</STRONG>. The latter were needed to support padding, and to
+ handle capabilities accessed by functions such as <STRONG>vidattr</STRONG> (which used
+ more than the two parameters supported by <STRONG>tgoto</STRONG>).
+
+ SVr3 introduced the functions for switching between terminal
+ descriptions; for example, <STRONG>set_curterm</STRONG>. Some changes reflected
+ incremental improvements to the SVr2 library.
+
+ <STRONG>o</STRONG> The <EM>TERMINAL</EM> type definition was introduced in SVr3.01, for the
+ <EM>term</EM> structure provided in SVr2.
+
+ <STRONG>o</STRONG> Various global variables such as <STRONG>boolnames</STRONG> were mentioned in the
+ programming manual at this point, though the variables had been
+ provided in SVr2.
+
+ SVr4 (1989) added the <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> functions.
+
+ Other low-level functions are declared in the <EM>curses</EM> header files of
+ Unix systems, but none are documented. Those noted as "obsolete" by
+ SVr3 remained in use by System V's <STRONG>vi(1)</STRONG> editor.