* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_util.3x,v 1.101 2024/04/20 21:20:07 tom Exp @
+ * @Id: curs_util.3x,v 1.110 2024/06/15 20:20:12 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_util 3x 2024-04-20 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_util 3x 2024-06-15 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_util 3x 2024-04-20 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_util 3x 2024-06-15 ncurses 6.5 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
<STRONG>void</STRONG> <STRONG>filter(void);</STRONG>
- <STRONG>void</STRONG> <STRONG>use_env(bool</STRONG> <EM>f</EM><STRONG>);</STRONG>
+ <STRONG>void</STRONG> <STRONG>use_env(bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>putwin(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>FILE</STRONG> <STRONG>*</STRONG><EM>filep</EM><STRONG>);</STRONG>
<STRONG>WINDOW</STRONG> <STRONG>*getwin(FILE</STRONG> <STRONG>*</STRONG><EM>filep</EM><STRONG>);</STRONG>
<EM>/*</EM> <EM>extensions</EM> <EM>*/</EM>
<STRONG>void</STRONG> <STRONG>nofilter(void);</STRONG>
- <STRONG>void</STRONG> <STRONG>use_tioctl(bool</STRONG> <EM>f</EM><STRONG>);</STRONG>
+ <STRONG>void</STRONG> <STRONG>use_tioctl(bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
</PRE><H3><a name="h3-unctrl">unctrl</a></H3><PRE>
- The <STRONG>unctrl</STRONG> routine returns a character string which is a printable
+ The <STRONG>unctrl</STRONG> routine returns a character string as a printable
representation of the character <EM>ch</EM>:
<STRONG>o</STRONG> Printable characters are displayed as themselves, e.g., a one-
implementations return rather than null.
The corresponding <STRONG>key_name</STRONG> returns a multibyte character string
- corresponding to the wide-character value <EM>w</EM>. The two functions
+ corresponding to the wide-character value <EM>wc</EM>. The two functions
(<STRONG>keyname</STRONG> and <STRONG>key_name</STRONG>) do not return the same set of strings:
<STRONG>o</STRONG> <STRONG>keyname</STRONG> returns null where <STRONG>key_name</STRONG> would display a meta character.
from the terminal database.
<STRONG>o</STRONG> <EM>ncurses</EM> re-fetches the value of the environment variables so that
- it is still the environment variables which set the screen size.
+ it is still the environment variables that set the screen size.
The <STRONG>use_env</STRONG> and <STRONG>use_tioctl</STRONG> routines combine as follows.
<STRONG>use_env</STRONG> <STRONG>use_tioctl</STRONG> <STRONG>Summary</STRONG>
-----------------------------------------------------------------
- <STRONG>TRUE</STRONG> <STRONG>FALSE</STRONG> This is the default behavior. <EM>ncurses</EM>
- uses operating system calls unless
- overridden by <EM>LINES</EM> or <EM>COLUMNS</EM>
+ <STRONG>TRUE</STRONG> <STRONG>FALSE</STRONG> <EM>ncurses</EM> uses operating system calls
+ unless overridden by <EM>LINES</EM> or <EM>COLUMNS</EM>
environment variables; default.
- <STRONG>TRUE</STRONG> <STRONG>TRUE</STRONG> <EM>ncurses</EM> updates <EM>LINES</EM> and <EM>COLUMNS</EM> based
+ <STRONG>TRUE</STRONG> <STRONG>TRUE</STRONG> <EM>ncurses</EM> updates <EM>LINES</EM> and <EM>COLUMNS</EM> based
on operating system calls.
- <STRONG>FALSE</STRONG> <STRONG>TRUE</STRONG> <EM>ncurses</EM> ignores <EM>LINES</EM> and <EM>COLUMNS</EM>, using
+ <STRONG>FALSE</STRONG> <STRONG>TRUE</STRONG> <EM>ncurses</EM> ignores <EM>LINES</EM> and <EM>COLUMNS</EM>, using
operating system calls to obtain size.
</PRE><H3><a name="h3-putwin_getwin">putwin, getwin</a></H3><PRE>
- The <STRONG>putwin</STRONG> routine writes all data associated with window (or pad) <EM>win</EM>
- into the file to which <EM>filep</EM> points. This information can be later
+ The <STRONG>putwin</STRONG> routine writes all data associated with window (or pad) <EM>win</EM>
+ into the file to which <EM>filep</EM> points. This information can be later
retrieved using the <STRONG>getwin</STRONG> function.
- The <STRONG>getwin</STRONG> routine reads window related data stored in the file by
- <STRONG>putwin</STRONG>. The routine then creates and initializes a new window using
- that data. It returns a pointer to the new window. There are a few
+ The <STRONG>getwin</STRONG> routine reads window related data stored in the file by
+ <STRONG>putwin</STRONG>. The routine then creates and initializes a new window using
+ that data. It returns a pointer to the new window. There are a few
caveats:
- <STRONG>o</STRONG> the data written is a copy of the <EM>WINDOW</EM> structure, and its
- associated character cells. The format differs between the wide-
- character (<EM>ncursesw</EM>) and non-wide (<EM>ncurses</EM>) libraries. You can
+ <STRONG>o</STRONG> the data written is a copy of the <EM>WINDOW</EM> structure, and its
+ associated character cells. The format differs between the wide-
+ character (<EM>ncursesw</EM>) and non-wide (<EM>ncurses</EM>) libraries. You can
transfer data between the two, however.
- <STRONG>o</STRONG> the retrieved window is always created as a top-level window (or
+ <STRONG>o</STRONG> the retrieved window is always created as a top-level window (or
pad), rather than a subwindow.
- <STRONG>o</STRONG> the window's character cells contain the color pair <EM>value</EM>, but not
- the actual color <EM>numbers</EM>. If cells in the retrieved window use
- color pairs which have not been created in the application using
+ <STRONG>o</STRONG> the window's character cells contain the color pair <EM>value</EM>, but not
+ the actual color <EM>numbers</EM>. If cells in the retrieved window use
+ color pairs that have not been created in the application using
<STRONG>init_pair</STRONG>, they will not be colored when the window is refreshed.
</PRE><H3><a name="h3-delay_output">delay_output</a></H3><PRE>
- The <STRONG>delay_output</STRONG> routine inserts an <EM>ms</EM> millisecond pause in output.
- Employ this function judiciously when terminal output uses padding,
- because <EM>ncurses</EM> transmits null characters (consuming CPU and I/O
- resources) instead of sleeping and requesting resumption from the
+ The <STRONG>delay_output</STRONG> routine inserts an <EM>ms</EM> millisecond pause in output.
+ Employ this function judiciously when terminal output uses padding,
+ because <EM>ncurses</EM> transmits null characters (consuming CPU and I/O
+ resources) instead of sleeping and requesting resumption from the
operating system. Padding is used unless:
<STRONG>o</STRONG> the terminal description has <STRONG>npc</STRONG> (<STRONG>no_pad_char</STRONG>) capability, or
<STRONG>o</STRONG> the environment variable <STRONG>NCURSES_NO_PADDING</STRONG> is set.
- If padding is not in use, <EM>ncurses</EM> uses <STRONG>napms</STRONG> to perform the delay. If
- the value of <EM>ms</EM> exceeds 30,000 (thirty seconds), it is capped at that
+ If padding is not in use, <EM>ncurses</EM> uses <STRONG>napms</STRONG> to perform the delay. If
+ the value of <EM>ms</EM> exceeds 30,000 (thirty seconds), it is capped at that
value.
</PRE><H3><a name="h3-flushinp">flushinp</a></H3><PRE>
- The <STRONG>flushinp</STRONG> routine throws away any typeahead that has been typed by
+ The <STRONG>flushinp</STRONG> routine throws away any typeahead that has been typed by
the user and has not yet been read by the program.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- Except for <STRONG>flushinp</STRONG>, routines that return an integer return <STRONG>ERR</STRONG> upon
- failure and <STRONG>OK</STRONG> (SVr4 specifies only "an integer value other than <STRONG>ERR</STRONG>")
+ Except for <STRONG>flushinp</STRONG>, routines that return an integer return <STRONG>ERR</STRONG> upon
+ failure and <STRONG>OK</STRONG> (SVr4 specifies only "an integer value other than <STRONG>ERR</STRONG>")
upon successful completion.
Routines that return pointers return <STRONG>NULL</STRONG> on error.
- X/Open Curses does not specify any error conditions. In this
+ X/Open Curses does not specify any error conditions. In this
implementation
<STRONG>flushinp</STRONG>
- returns an error if the terminal was not initialized.
+ returns <STRONG>ERR</STRONG> if the terminal was not initialized.
<STRONG>putwin</STRONG>
- returns an error if the associated <STRONG>fwrite</STRONG> calls return an
- error.
+ returns <STRONG>ERR</STRONG> if the associated <STRONG>write(2)</STRONG> calls return <STRONG>ERR</STRONG>.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
</PRE><H3><a name="h3-keyname">keyname</a></H3><PRE>
The <STRONG>keyname</STRONG> function may return the names of user-defined string
- capabilities which are defined in the terminfo entry via the <STRONG>-x</STRONG> option
- of <STRONG>tic</STRONG>. This implementation automatically assigns at run-time keycodes
- to user-defined strings which begin with "k". The keycodes start at
- KEY_MAX, but are not guaranteed to be the same value for different runs
- because user-defined codes are merged from all terminal descriptions
- which have been loaded. The <STRONG><A HREF="curs_extend.3x.html">use_extended_names(3x)</A></STRONG> function controls
- whether this data is loaded when the terminal description is read by
- the library.
+ capabilities that are defined in the terminfo entry via the <STRONG>-x</STRONG> option
+ of <STRONG>tic</STRONG>. This implementation automatically assigns at run-time key
+ codes to user-defined strings that begin with "k". The key codes start
+ at KEY_MAX, but are not guaranteed to be the same value for different
+ runs because user-defined codes are merged from all terminal
+ descriptions that have been loaded. The <STRONG><A HREF="curs_extend.3x.html">use_extended_names(3x)</A></STRONG>
+ function controls whether this data is loaded when the terminal
+ description is read by the library.
</PRE><H3><a name="h3-nofilter_use_tioctl">nofilter, use_tioctl</a></H3><PRE>
older <EM>ncurses</EM> versions. This implementation (as well as the X/Open
variant of Solaris curses, dated 1995) uses textual dumps.
- The implementations which use binary dumps use block-I/O (the
- <STRONG>fwrite</STRONG> and <STRONG>fread</STRONG> functions). Those that use textual dumps use
- buffered-I/O. A few applications may happen to write extra data in
- the file using these functions. Doing that can run into problems
- mixing block- and buffered-I/O. This implementation reduces the
- problem on writes by flushing the output. However, reading from a
- file written using mixed schemes may not be successful.
+ The implementations that use binary dumps use block-I/O (<STRONG>write(2)</STRONG>
+ and <STRONG>read(2)</STRONG> functions). Those that use textual dumps use buffered-
+ I/O. A few applications may happen to write extra data in the file
+ using these functions. Doing that can run into problems mixing
+ block- and buffered-I/O. This implementation reduces the problem
+ on writes by flushing the output. However, reading from a file
+ written using mixed schemes may not be successful.
</PRE><H3><a name="h3-unctrl_wunctrl">unctrl, wunctrl</a></H3><PRE>
<STRONG>use_env</STRONG> is not provided by other implementations of curses.
+</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
+ 4BSD (1980) defined <EM>unctrl</EM> (as a macro, in <EM>unctrl.h</EM>).
+
+ SVr2 (1984) introduced <EM>delay</EM><STRONG>_</STRONG><EM>output</EM>, <EM>flushinp</EM>, and <EM>keyname</EM>.
+
+ SVr3 (1987) added <EM>filter</EM>. Later that year, SVr3.1 brought <EM>getwin</EM> and
+ <EM>putwin</EM>, reading and writing window dumps with <STRONG>fread(3)</STRONG> and <STRONG>fwrite(3)</STRONG>,
+ respectively.
+
+ SVr4 (1989) supplied <EM>use</EM><STRONG>_</STRONG><EM>env</EM>.
+
+ X/Open Curses Issue 4 (1995) specified <EM>key</EM><STRONG>_</STRONG><EM>name</EM> and <EM>wunctrl</EM>.
+
+ <EM>ncurses</EM> 5.6 (2006) added <EM>nofilter</EM>, and 6.0 (2015) <EM>use</EM><STRONG>_</STRONG><EM>tioctl</EM>.
+
+
</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_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>,
<STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>, <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>,
-ncurses 6.
4 2024-04-20 <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
+ncurses 6.
5 2024-06-15 <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h3-use_env_use_tioctl">use_env, use_tioctl</a></li>
</ul>
</li>
+<li><a href="#h2-HISTORY">HISTORY</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
</ul>
</div>
projects / ncurses.git / blobdiff