| <!-- |
| * t |
| **************************************************************************** |
| * Copyright 2018-2023,2024 Thomas E. Dickey * |
| * Copyright 1998-2016,2017 Free Software Foundation, Inc. * |
| * * |
| * Permission is hereby granted, free of charge, to any person obtaining a * |
| * copy of this software and associated documentation files (the * |
| * "Software"), to deal in the Software without restriction, including * |
| * without limitation the rights to use, copy, modify, merge, publish, * |
| * distribute, distribute with modifications, sublicense, and/or sell * |
| * copies of the Software, and to permit persons to whom the Software is * |
| * furnished to do so, subject to the following conditions: * |
| * * |
| * The above copyright notice and this permission notice shall be included * |
| * in all copies or substantial portions of the Software. * |
| * * |
| * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * |
| * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * |
| * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * |
| * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * |
| * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * |
| * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * |
| * THE USE OR OTHER DEALINGS IN THE SOFTWARE. * |
| * * |
| * Except as contained in this notice, the name(s) of the above copyright * |
| * holders shall not be used in advertising or otherwise to promote the * |
| * sale, use or other dealings in this Software without prior written * |
| * authorization. * |
| **************************************************************************** |
| * @Id: curs_terminfo.3x,v 1.136 2024/04/14 00:14:40 tom Exp @ |
| --> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> |
| <HTML> |
| <HEAD> |
| <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> |
| <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> |
| <TITLE>curs_terminfo 3x 2024-04-13 ncurses 6.5 Library calls</TITLE> |
| <link rel="author" href="mailto:bug-ncurses@gnu.org"> |
| |
| </HEAD> |
| <BODY> |
| <H1 class="no-header">curs_terminfo 3x 2024-04-13 ncurses 6.5 Library calls</H1> |
| <PRE> |
| <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> |
| |
| |
| |
| |
| </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> |
| <STRONG>del_curterm</STRONG>, <STRONG>mvcur</STRONG>, <STRONG>putp</STRONG>, <STRONG>restartterm</STRONG>, <STRONG>set_curterm</STRONG>, <STRONG>setupterm</STRONG>, |
| <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG>, <STRONG>tigetstr</STRONG>, <STRONG>tiparm</STRONG>, <STRONG>tiparm_s</STRONG>, <STRONG>tiscan_s</STRONG>, <STRONG>tparm</STRONG>, |
| <STRONG>tputs</STRONG>, <STRONG>vid_attr</STRONG>, <STRONG>vid_puts</STRONG>, <STRONG>vidattr</STRONG>, <STRONG>vidputs</STRONG> - <EM>curses</EM> interfaces to |
| <EM>terminfo</EM> database |
| |
| |
| </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> |
| <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> |
| <STRONG>#include</STRONG> <STRONG><term.h></STRONG> |
| |
| <STRONG>TERMINAL</STRONG> <STRONG>*cur_term;</STRONG> |
| |
| <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolnames[];</STRONG> |
| <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolcodes[];</STRONG> |
| <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolfnames[];</STRONG> |
| <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numnames[];</STRONG> |
| <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numcodes[];</STRONG> |
| <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numfnames[];</STRONG> |
| <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strnames[];</STRONG> |
| <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strcodes[];</STRONG> |
| <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strfnames[];</STRONG> |
| |
| <STRONG>int</STRONG> <STRONG>setupterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>filedes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG> |
| <STRONG>TERMINAL</STRONG> <STRONG>*set_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>nterm</EM><STRONG>);</STRONG> |
| <STRONG>int</STRONG> <STRONG>del_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>oterm</EM><STRONG>);</STRONG> |
| <STRONG>int</STRONG> <STRONG>restartterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>filedes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG> |
| |
| <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> ...<STRONG>);</STRONG> |
| <EM>/*</EM> <EM>or</EM> <EM>*/</EM> |
| <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>long</STRONG> <EM>p1</EM> ... <STRONG>long</STRONG> <EM>p9</EM><STRONG>);</STRONG> |
| |
| <STRONG>int</STRONG> <STRONG>tputs(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>affcnt</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG> |
| <STRONG>int</STRONG> <STRONG>putp(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> |
| |
| <STRONG>int</STRONG> <STRONG>vidputs(chtype</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG> |
| <STRONG>int</STRONG> <STRONG>vidattr(chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG> |
| <STRONG>int</STRONG> <STRONG>vid_puts(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG> |
| <STRONG>int</STRONG> <STRONG>vid_attr(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG> |
| |
| <STRONG>int</STRONG> <STRONG>mvcur(int</STRONG> <EM>oldrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>oldcol</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newcol</EM><STRONG>);</STRONG> |
| |
| <STRONG>int</STRONG> <STRONG>tigetflag(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>cap-code</EM><STRONG>);</STRONG> |
| <STRONG>int</STRONG> <STRONG>tigetnum(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>cap-code</EM><STRONG>);</STRONG> |
| <STRONG>char</STRONG> <STRONG>*tigetstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>cap-code</EM><STRONG>);</STRONG> |
| |
| <STRONG>char</STRONG> <STRONG>*tiparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> ...<STRONG>);</STRONG> |
| |
| <EM>/*</EM> <EM>extensions</EM> <EM>*/</EM> |
| <STRONG>char</STRONG> <STRONG>*tiparm_s(int</STRONG> <EM>expected</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>mask</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG> |
| <STRONG>int</STRONG> <STRONG>tiscan_s(int</STRONG> <STRONG>*</STRONG><EM>expected</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>mask</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> |
| |
| <EM>/*</EM> <EM>deprecated</EM> <EM>*/</EM> |
| <STRONG>int</STRONG> <STRONG>setterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>);</STRONG> |
| |
| |
| </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> |
| These low-level functions must be called by programs that deal directly |
| with the <EM>terminfo</EM> database to handle certain terminal capabilities, |
| such as programming function keys. For all other functionality, <EM>curses</EM> |
| functions 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 and codes 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 <EM>curses</EM> 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="term_variables.3x.html">term_variables(3x)</A></STRONG>. |
| |
| Applications can use the terminal capabilities either directly (via |
| header definitions), or by special functions. The header files |
| <EM>curses.h</EM> and <EM>term.h</EM> should be included (in that order) to get the |
| definitions for these strings, numbers, and flags. |
| |
| The <EM>terminfo</EM> 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 <EM>terminfo</EM> are used. |
| |
| <STRONG>o</STRONG> Otherwise, if the environment variables <EM>LINES</EM> and <EM>COLUMNS</EM> 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 <EM>terminfo</EM> database are |
| used. |
| |
| Parameterized strings should be passed through <STRONG>tparm</STRONG> to instantiate |
| them. All <EM>terminfo</EM> strings (including the output of <STRONG>tparm</STRONG>) should be |
| sent to the terminal device with <STRONG>tputs</STRONG> or <STRONG>putp</STRONG>. Call <STRONG>reset_shell_mode</STRONG> |
| to restore the terminal modes before exiting; see <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>. |
| |
| Programs that 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 that 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. |
| |
| <STRONG>setupterm</STRONG> reads in the <EM>terminfo</EM> database, initializing the <EM>terminfo</EM> |
| structures, but does not set up the output virtualization structures |
| used by <EM>curses</EM>. Its parameters follow. |
| |
| <EM>term</EM> is the terminal type, a character string. If <EM>term</EM> is null, the |
| environment variable <EM>TERM</EM> is read. |
| |
| <EM>filedes</EM> |
| is the file descriptor used for getting and setting terminal |
| I/O modes. |
| |
| Higher-level applications use <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG> to initialize the |
| terminal, passing an output <EM>stream</EM> rather than a <EM>descriptor</EM>. |
| In <EM>curses</EM>, the two are the same because <STRONG>newterm</STRONG> calls |
| <STRONG>setupterm</STRONG>, passing the file descriptor derived from its output |
| stream parameter. |
| |
| <EM>errret</EM> |
| points to an optional location where an error status can be |
| returned 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 |
| status 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, and cannot be used |
| for <EM>curses</EM> applications. |
| |
| <STRONG>setupterm</STRONG> determines if the entry is a hardcopy type by |
| checking the <STRONG>hardcopy</STRONG> (<STRONG>hc</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 <EM>curses</EM> |
| applications to run. |
| |
| <STRONG>setupterm</STRONG> determines if the entry is a generic type by |
| checking the <STRONG>generic_type</STRONG> (<STRONG>gn</STRONG>) capability. |
| |
| <STRONG>-1</STRONG> means that the <EM>terminfo</EM> database could not be found. |
| |
| If <EM>errret</EM> is null, <STRONG>setupterm</STRONG> reports an error message upon |
| finding an error and exits. Thus, the simplest call is: |
| |
| setupterm((char *)0, 1, (int *)0); |
| |
| 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> |
| <STRONG>setupterm</STRONG> stores its information about the terminal in a <EM>TERMINAL</EM> |
| 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 |
| terminal's capabilities in memory. If it is called for different |
| terminal types, <STRONG>setupterm</STRONG> allocates new storage for each set of |
| terminal capabilities. |
| |
| <STRONG>set_curterm</STRONG> sets <STRONG>cur_term</STRONG> to <EM>nterm</EM>, and makes all of the <EM>terminfo</EM> |
| Boolean, numeric, and string variables use the values from <EM>nterm</EM>. It |
| returns the old value of <STRONG>cur_term</STRONG>. |
| |
| <STRONG>del_curterm</STRONG> 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 <EM>terminfo</EM> Boolean, numeric, and string variables thereafter may |
| refer to invalid memory locations until another <STRONG>setupterm</STRONG> has been |
| called. |
| |
| <STRONG>restartterm</STRONG> 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). <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 terminal state bits, calls |
| <STRONG>setupterm</STRONG>, and then restores the bits. |
| |
| |
| </PRE><H3><a name="h3-Formatting-Output">Formatting Output</a></H3><PRE> |
| <STRONG>tparm</STRONG> instantiates the string <EM>str</EM> with parameters <EM>pi</EM>. A pointer is |
| returned to the result of <EM>str</EM> with the parameters applied. Application |
| developers should keep in mind these quirks of the interface: |
| |
| <STRONG>o</STRONG> Although <STRONG>tparm</STRONG>'s actual parameters may be integers or strings, the |
| prototype expects <EM>long</EM> (integer) values. |
| |
| <STRONG>o</STRONG> Aside from the <STRONG>set_attributes</STRONG> (<STRONG>sgr</STRONG>) capability, most terminal |
| capabilities require no more than one or two parameters. |
| |
| <STRONG>o</STRONG> Padding information is ignored by <STRONG>tparm</STRONG>; it is interpreted by |
| <STRONG>tputs</STRONG>. |
| |
| <STRONG>o</STRONG> The capability string is null-terminated. Use "\200" where an |
| ASCII NUL is needed in the output. |
| |
| <STRONG>tiparm</STRONG> is a newer form of <STRONG>tparm</STRONG> which uses <EM>stdarg.h</EM> rather than a |
| fixed-parameter list. Its numeric parameters are <EM>int</EM>s rather than |
| <EM>long</EM>s. |
| |
| Both <STRONG>tparm</STRONG> and <STRONG>tiparm</STRONG> assume that the application passes parameters |
| consistent with the terminal description. Two extensions are provided |
| as alternatives to deal with untrusted data. |
| |
| <STRONG>o</STRONG> <STRONG>tiparm_s</STRONG> is an extension which is a safer formatting function than |
| <STRONG>tparm</STRONG> or <STRONG>tiparm</STRONG>, because it allows the developer to tell the <EM>curses</EM> |
| library how many parameters to expect in the parameter list, and |
| which may be string parameters. |
| |
| The <EM>mask</EM> parameter has one bit set for each of the parameters (up |
| to 9) passed as <EM>char</EM> pointers rather than numbers. |
| |
| <STRONG>o</STRONG> The extension <STRONG>tiscan_s</STRONG> allows the application to inspect a |
| formatting capability to see what the <EM>curses</EM> library would assume. |
| |
| |
| </PRE><H3><a name="h3-Output-Functions">Output Functions</a></H3><PRE> |
| String capabilities can contain padding information, a time delay |
| (accommodating performance limitations of hardware terminals) expressed |
| as <STRONG>$<</STRONG><EM>n</EM><STRONG>></STRONG>, where <EM>n</EM> is a nonnegative integral count of milliseconds. If <EM>n</EM> |
| exceeds 30,000 (thirty seconds), it is capped at that value. |
| |
| <STRONG>tputs</STRONG> interprets time-delay information in the string <EM>str</EM> and outputs |
| it, executing the delays: |
| |
| <STRONG>o</STRONG> The <EM>str</EM> parameter must be a <EM>terminfo</EM> string variable or the return |
| value of <STRONG>tparm</STRONG>, <STRONG>tiparm</STRONG>, <STRONG>tgetstr</STRONG>, or <STRONG>tgoto</STRONG>. |
| |
| The <STRONG>tgetstr</STRONG> and <STRONG>tgoto</STRONG> functions are part of the <EM>termcap</EM> interface, |
| which happens to share these function names with the <EM>terminfo</EM> API. |
| |
| <STRONG>o</STRONG> <EM>affcnt</EM> is the number of lines affected, or <STRONG>1</STRONG> if not applicable. |
| |
| <STRONG>o</STRONG> <EM>putc</EM> is a <EM>putchar</EM>-like function to which the characters are passed, |
| one at a time. |
| |
| If <STRONG>tputs</STRONG> processes a time-delay, it uses the <STRONG><A HREF="curs_util.3x.html">delay_output(3x)</A></STRONG> |
| function, routing any resulting padding characters through this |
| function. |
| |
| <STRONG>putp</STRONG> calls "<STRONG>tputs(</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>putchar)</STRONG>". The output of <STRONG>putp</STRONG> always goes to |
| <STRONG>stdout</STRONG>, rather than the <EM>filedes</EM> specified in <STRONG>setupterm</STRONG>. |
| |
| <STRONG>vidputs</STRONG> displays the string on the terminal in the video attribute mode |
| <EM>attrs</EM>, which is any combination of the attributes listed in <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>. |
| The characters are passed to the <EM>putchar</EM>-like function <EM>putc</EM>. |
| |
| <STRONG>vidattr</STRONG> is like <STRONG>vidputs</STRONG>, except that it outputs through <STRONG>putchar(3)</STRONG>. |
| |
| <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> correspond to <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG>, respectively. |
| They use multiple parameters to represent the character attributes and |
| color; namely, |
| |
| <STRONG>o</STRONG> <EM>attrs</EM>, of type <EM>attr</EM><STRONG>_</STRONG><EM>t</EM>, for the attributes and |
| |
| <STRONG>o</STRONG> <EM>pair</EM>, of type <EM>short</EM>, for the color pair number. |
| |
| Use the attribute constants prefixed with "<STRONG>WA_</STRONG>" with <STRONG>vid_attr</STRONG> and |
| <STRONG>vid_puts</STRONG>. |
| |
| X/Open Curses reserves the <EM>opts</EM> argument for future use, saying that |
| applications must provide a null pointer for that argument; but see |
| section "EXTENSIONS" below. |
| |
| <STRONG>mvcur</STRONG> provides low-level cursor motion. It takes effect immediately |
| (rather than at the next refresh). Unlike the other low-level output |
| functions, which either write to the standard output or pass an output |
| function parameter, <STRONG>mvcur</STRONG> uses an output file descriptor derived from |
| the output stream parameter of <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>. |
| |
| While <STRONG>putp</STRONG> and <STRONG>mvcur</STRONG> are low-level functions that do not use high-level |
| <EM>curses</EM> state, <EM>ncurses</EM> declares them in <EM>curses.h</EM> because System V did |
| this (see section "HISTORY" below). |
| |
| |
| </PRE><H3><a name="h3-Terminal-Capability-Functions">Terminal Capability Functions</a></H3><PRE> |
| <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG>, and <STRONG>tigetstr</STRONG> return the value of the capability |
| corresponding to the <EM>terminfo</EM> <EM>cap-code</EM>, such as <STRONG>xenl</STRONG>, passed to them. |
| The <EM>cap-code</EM> for each capability is given in the table column entitled |
| <EM>cap-code</EM> code in the capabilities section of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. |
| |
| These functions return special values to denote errors. |
| |
| <STRONG>tigetflag</STRONG> returns |
| |
| <STRONG>-1</STRONG> if <EM>cap-code</EM> is not a Boolean capability, or |
| |
| <STRONG>0</STRONG> if it is canceled or absent from the terminal description. |
| |
| <STRONG>tigetnum</STRONG> returns |
| |
| <STRONG>-2</STRONG> if <EM>cap-code</EM> is not a numeric capability, or |
| |
| <STRONG>-1</STRONG> if it is canceled or absent from the terminal description. |
| |
| <STRONG>tigetstr</STRONG> returns |
| |
| <STRONG>(char</STRONG> <STRONG>*)-1</STRONG> |
| if <EM>cap-code</EM> is not a string capability, or |
| |
| <STRONG>0</STRONG> if it is canceled or absent from the terminal description. |
| |
| |
| </PRE><H3><a name="h3-Terminal-Capability-Names">Terminal Capability Names</a></H3><PRE> |
| These null-terminated arrays contain |
| |
| <STRONG>o</STRONG> the short <EM>terminfo</EM> names ("codes"), |
| |
| <STRONG>o</STRONG> the <EM>termcap</EM> names ("names"), and |
| |
| <STRONG>o</STRONG> the long <EM>terminfo</EM> names ("fnames") |
| |
| for each of the predefined <EM>terminfo</EM> variables: |
| |
| <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*boolnames[]</STRONG>, <STRONG>*boolcodes[]</STRONG>, <STRONG>*boolfnames[]</STRONG> |
| <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*numnames[]</STRONG>, <STRONG>*numcodes[]</STRONG>, <STRONG>*numfnames[]</STRONG> |
| <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*strnames[]</STRONG>, <STRONG>*strcodes[]</STRONG>, <STRONG>*strfnames[]</STRONG> |
| |
| |
| </PRE><H3><a name="h3-Releasing-Memory">Releasing Memory</a></H3><PRE> |
| Each successful call to <STRONG>setupterm</STRONG> allocates memory to hold the terminal |
| description. As a side effect, it sets <STRONG>cur_term</STRONG> to point to this |
| memory. If an application calls |
| |
| del_curterm(cur_term); |
| |
| the memory will be freed. |
| |
| The formatting functions <STRONG>tparm</STRONG> and <STRONG>tiparm</STRONG> extend the storage allocated |
| by <STRONG>setupterm</STRONG> as follows. |
| |
| <STRONG>o</STRONG> They add the "static" <EM>terminfo</EM> variables [a-z]. Before <EM>ncurses</EM> |
| 6.3, those were shared by all screens. With <EM>ncurses</EM> 6.3, those are |
| allocated per screen. See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. |
| |
| <STRONG>o</STRONG> To improve performance, <EM>ncurses</EM> 6.3 caches the result of analyzing |
| <EM>terminfo</EM> strings for their parameter types. That is stored as a |
| binary tree referenced from the <EM>TERMINAL</EM> structure. |
| |
| The higher-level <STRONG>initscr</STRONG> and <STRONG>newterm</STRONG> functions use <STRONG>setupterm</STRONG>. Normally |
| they do not free this memory, but it is possible to do that using the |
| <STRONG><A HREF="curs_initscr.3x.html">delscreen(3x)</A></STRONG> function. |
| |
| |
| </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> |
| X/Open Curses defines no failure conditions. In <EM>ncurses</EM>, |
| |
| <STRONG>del_curtem</STRONG> |
| fails if its terminal parameter is null. |
| |
| <STRONG>putp</STRONG> calls <STRONG>tputs</STRONG>, returning the same error codes. |
| |
| <STRONG>restartterm</STRONG> |
| fails if the associated call to <STRONG>setupterm</STRONG> returns an error. |
| |
| <STRONG>setupterm</STRONG> |
| fails if it cannot allocate enough memory, or create the initial |
| windows (<STRONG>stdscr</STRONG>, <STRONG>curscr</STRONG>, and <STRONG>newscr</STRONG>) Other error conditions are |
| documented above. |
| |
| <STRONG>tparm</STRONG> |
| returns a null pointer if the capability would require unexpected |
| parameters; that is, too many, too few, or incorrect types |
| (strings where integers are expected, or vice versa). |
| |
| <STRONG>tputs</STRONG> |
| fails if the string parameter is null. It does not detect I/O |
| errors: X/Open Curses states that <STRONG>tputs</STRONG> ignores the return value |
| of the output function <EM>putc</EM>. |
| |
| |
| </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> |
| The <STRONG>vid_attr</STRONG> function in <EM>ncurses</EM> is a special case. It was originally |
| implemented based on a draft of X/Open Curses, as a macro, before other |
| parts of the <EM>ncurses</EM> wide-character API were developed, and unlike the |
| other wide-character functions, is also provided in the non-wide- |
| character configuration. |
| |
| |
| </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> |
| The functions marked as extensions were designed for <EM>ncurses</EM>, and are |
| not found in SVr4 <EM>curses</EM>, 4.4BSD <EM>curses</EM>, or any other previous <EM>curses</EM> |
| implementation. |
| |
| <EM>ncurses</EM> allows <EM>opts</EM> to be a pointer to <EM>int</EM>, which overrides the <EM>pair</EM> |
| (<EM>short</EM>) argument. |
| |
| |
| </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> |
| <STRONG>setterm</STRONG> is not described by X/Open and must be considered non-portable. |
| All other functions are as described by X/Open. |
| |
| |
| </PRE><H3><a name="h3-Compatibility-Macros">Compatibility Macros</a></H3><PRE> |
| This implementation provides a few macros for compatibility with |
| systems before SVr4 (see section "HISTORY" below). They include |
| <STRONG>Bcrmode</STRONG>, <STRONG>Bfixterm</STRONG>, <STRONG>Bgettmode</STRONG>, <STRONG>Bnocrmode</STRONG>, <STRONG>Bresetterm</STRONG>, <STRONG>Bsaveterm</STRONG>, and |
| <STRONG>Bsetterm</STRONG>. |
| |
| In SVr4, these are found in <EM>curses.h</EM>, but except for <STRONG>setterm</STRONG>, are |
| likewise macros. The one function, <STRONG>setterm</STRONG>, is mentioned in the manual |
| page. It further notes that <STRONG>setterm</STRONG> was replaced by <STRONG>setupterm</STRONG>, stating |
| that the call |
| setupterm(<EM>term</EM>, 1, (int *)0) |
| provides the same functionality as <STRONG>setterm(</STRONG><EM>term</EM><STRONG>)</STRONG>, discouraging the |
| latter for new programs. <EM>ncurses</EM> implements each of these symbols as |
| macros for BSD <EM>curses</EM> compatibility. |
| |
| |
| </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. |
| |
| |
| </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> |
| <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>, <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>, |
| <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, |
| <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> |
| |
| |
| |
| ncurses 6.5 2024-04-13 <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> |
| </PRE> |
| <div class="nav"> |
| <ul> |
| <li><a href="#h2-NAME">NAME</a></li> |
| <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> |
| <li><a href="#h2-DESCRIPTION">DESCRIPTION</a> |
| <ul> |
| <li><a href="#h3-Initialization">Initialization</a></li> |
| <li><a href="#h3-The-Terminal-State">The Terminal State</a></li> |
| <li><a href="#h3-Formatting-Output">Formatting Output</a></li> |
| <li><a href="#h3-Output-Functions">Output Functions</a></li> |
| <li><a href="#h3-Terminal-Capability-Functions">Terminal Capability Functions</a></li> |
| <li><a href="#h3-Terminal-Capability-Names">Terminal Capability Names</a></li> |
| <li><a href="#h3-Releasing-Memory">Releasing Memory</a></li> |
| </ul> |
| </li> |
| <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> |
| <li><a href="#h2-NOTES">NOTES</a></li> |
| <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> |
| <li><a href="#h2-PORTABILITY">PORTABILITY</a> |
| <ul> |
| <li><a href="#h3-Compatibility-Macros">Compatibility Macros</a></li> |
| <li><a href="#h3-Legacy-Data">Legacy Data</a></li> |
| <li><a href="#h3-Output-Buffering">Output Buffering</a></li> |
| <li><a href="#h3-Function-Prototypes">Function Prototypes</a></li> |
| <li><a href="#h3-Other-Portability-Issues">Other Portability Issues</a></li> |
| </ul> |
| </li> |
| <li><a href="#h2-HISTORY">HISTORY</a></li> |
| <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> |
| </ul> |
| </div> |
| </BODY> |
| </HTML> |