X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_util.3x.html;h=6d04cda35e549150dce18402e218498ce0b465c6;hb=122d3739b3c11c83decc625d53f26fff6e825710;hp=362169c2a9f962f2d4a5991f79849b76604922e1;hpb=d1a029866f6d84087781eaa81de19949d8533426;p=ncurses.git diff --git a/doc/html/man/curs_util.3x.html b/doc/html/man/curs_util.3x.html index 362169c2..6d04cda3 100644 --- a/doc/html/man/curs_util.3x.html +++ b/doc/html/man/curs_util.3x.html @@ -28,19 +28,19 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_util.3x,v 1.72 2023/08/05 13:34:35 tom Exp @ + * @Id: curs_util.3x,v 1.88 2023/10/14 22:26:23 tom Exp @ -->
-curs_util(3x) Library calls curs_util(3x) @@ -48,8 +48,8 @@
- delay_output, filter, flushinp, getwin, key_name, keyname, nofilter, - putwin, unctrl, use_env, use_tioctl, wunctrl - miscellaneous curses + delay_output, filter, flushinp, getwin, key_name, keyname, nofilter, + putwin, unctrl, use_env, use_tioctl, wunctrl - miscellaneous curses utility routines @@ -72,7 +72,7 @@ int delay_output(int ms); int flushinp(void); - /* extensions */ + /* extensions */ void nofilter(void); void use_tioctl(bool f); @@ -80,11 +80,11 @@
- The unctrl routine returns a character string which is a printable rep- - resentation of the character c: + The unctrl routine returns a character string which is a printable + representation of the character c: - o Printable characters are displayed as themselves, e.g., a one-char- - acter string containing the key. + o Printable characters are displayed as themselves, e.g., a one- + character string containing the key. o Control characters are displayed in the ^X notation. @@ -93,13 +93,13 @@ o DEL (character 127) is displayed as ^?. o Values above 128 are either meta characters (if the screen has not - been initialized, or if meta(3x) has been called with a TRUE param- - eter), shown in the M-X notation, or are displayed as themselves. - In the latter case, the values may not be printable; this follows - the X/Open specification. + been initialized, or if meta(3x) has been called with a TRUE + parameter), shown in the M-X notation, or are displayed as + themselves. In the latter case, the values may not be printable; + this follows the X/Open specification. - The corresponding wunctrl returns a printable representation of a com- - plex character c. + The corresponding wunctrl returns a printable representation of a + complex character c. In both unctrl and wunctrl the attributes and color associated with the character parameter are ignored. @@ -109,20 +109,20 @@ The keyname routine returns a character string corresponding to the key c. Key codes are different from character codes. - o Key codes below 256 are characters. They are displayed using unc- - trl. + o Key codes below 256 are characters. They are displayed using + unctrl. o Values above 256 may be the codes for function keys. The function key name is displayed. o Otherwise (if there is no corresponding name and the key is not a character) the function returns null, to denote an error. X/Open - also lists an "UNKNOWN KEY" return value, which some implementa- - tions return rather than null. + also lists an "UNKNOWN KEY" return value, which some + implementations return rather than null. - The corresponding key_name returns a multibyte character string corre- - sponding to the wide-character value w. The two functions (keyname and - key_name) do not return the same set of strings: + The corresponding key_name returns a multibyte character string + corresponding to the wide-character value w. The two functions + (keyname and key_name) do not return the same set of strings: o keyname returns null where key_name would display a meta character. @@ -135,8 +135,8 @@ o LINES is set to 1; - o the capabilities clear, cud1, cud, cup, cuu1, cuu, vpa are dis- - abled; + o the capabilities clear, cud1, cud, cup, cuu1, cuu, vpa are + disabled; o the capability ed is disabled if bce is set; @@ -150,26 +150,26 @@
The use_env routine, if used, should be called before initscr or - newterm are called (because those compute the screen size). It modi- - fies the way ncurses treats environment variables when determining the - screen size. + newterm are called (because those compute the screen size). It + modifies the way ncurses treats environment variables when determining + the screen size. - o Normally ncurses looks first at the terminal database for the + o Normally ncurses looks first at the terminal database for the screen size. - If use_env was called with FALSE for parameter, it stops here un- - less use_tioctl was also called with TRUE for parameter. + If use_env was called with FALSE for parameter, it stops here + unless use_tioctl was also called with TRUE for parameter. o Then it asks for the screen size via operating system calls. If successful, it overrides the values from the terminal database. o Finally (unless use_env was called with FALSE parameter), ncurses examines the LINES or COLUMNS environment variables, using a value - in those to override the results from the operating system or ter- - minal database. + in those to override the results from the operating system or + terminal database. - Ncurses also updates the screen size in response to SIGWINCH, un- - less overridden by the LINES or COLUMNS environment variables, + Ncurses also updates the screen size in response to SIGWINCH, + unless overridden by the LINES or COLUMNS environment variables,
@@ -188,37 +188,34 @@ o ncurses re-fetches the value of the environment variables so that it is still the environment variables which set the screen size. - The use_env and use_tioctl routines combine as summarized here: + The use_env and use_tioctl routines combine as follows. - use_env use_tioctl Summary - ---------------------------------------------------------------- - TRUE FALSE This is the default behavior. ncurses - uses operating system calls unless over- - ridden by $LINES or $COLUMNS environment - variables. - TRUE TRUE ncurses updates $LINES and $COLUMNS - based on operating system calls. - FALSE TRUE ncurses ignores $LINES and $COLUMNS, us- - es operating system calls to obtain - size. - FALSE FALSE ncurses relies on the terminal database - to determine size. + use_env use_tioctl Summary + ----------------------------------------------------------------- + TRUE FALSE This is the default behavior. ncurses + uses operating system calls unless + overridden by LINES or COLUMNS + environment variables; default. + TRUE TRUE ncurses updates LINES and COLUMNS based + on operating system calls. + FALSE TRUE ncurses ignores LINES and COLUMNS, using + operating system calls to obtain size.
The putwin routine writes all data associated with window (or pad) win - into the file to which filep points. This information can be later re- - trieved using the getwin function. + into the file to which filep points. This information can be later + retrieved using the getwin function. The getwin routine reads window related data stored in the file by putwin. 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: - o the data written is a copy of the WINDOW structure, and its associ- - ated character cells. The format differs between the wide-charac- - ter (ncursesw) and non-wide (ncurses) libraries. You can transfer - data between the two, however. + o the data written is a copy of the WINDOW structure, and its + associated character cells. The format differs between the wide- + character (ncursesw) and non-wide (ncurses) libraries. You can + transfer data between the two, however. o the retrieved window is always created as a top-level window (or pad), rather than a subwindow. @@ -231,19 +228,28 @@
The delay_output routine inserts an ms millisecond pause in output. - This routine should not be used extensively because padding characters - are used rather than a CPU pause. If no padding character is speci- - fied, this uses napms to perform the delay. + Employ this function judiciously when terminal output uses padding, + because ncurses transmits null characters (consuming CPU and I/O + resources) instead of sleeping and requesting resumption from the + operating system. Padding is used unless: + + o the terminal description has npc (no_pad_char) capability, or + + o the environment variable NCURSES_NO_PADDING is set. + + If padding is not in use, ncurses uses napms to perform the delay. If + the value of ms exceeds 30,000 (thirty seconds), it is capped at that + value.
- The flushinp routine throws away any typeahead that has been typed by + The flushinp routine throws away any typeahead that has been typed by the user and has not yet been read by the program.
- Except for flushinp, routines that return an integer return ERR upon - failure and OK (SVr4 specifies only "an integer value other than ERR") + Except for flushinp, routines that return an integer return ERR upon + failure and OK (SVr4 specifies only "an integer value other than ERR") upon successful completion. Routines that return pointers return NULL on error. @@ -254,23 +260,36 @@ returns an error if the terminal was not initialized. putwin - returns an error if the associated fwrite calls return an er- - ror. + returns an error if the associated fwrite calls return an + error.
- The SVr4 documentation describes the action of filter only in the - vaguest terms. The description here is adapted from the XSI Curses + The SVr4 documentation describes the action of filter only in the + vaguest terms. The description here is adapted from the XSI Curses standard (which erroneously fails to describe the disabling of cuu). +
+ The limitation to 30 seconds and the use of napms differ from other + implementations. + + o SVr4 curses does not delay if no padding character is available. + + o NetBSD curses uses napms when no padding character is available, + but does not take timing into account when using the padding + character. + + Neither limits the delay. + +
- The keyname function may return the names of user-defined string capa- - bilities which are defined in the terminfo entry via the -x option of - tic. This implementation automatically assigns at run-time keycodes to - user-defined strings which begin with "k". The keycodes start at + The keyname function may return the names of user-defined string + capabilities which are defined in the terminfo entry via the -x option + of tic. 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 use_extended_names(3x) function controls @@ -281,16 +300,16 @@
The nofilter and use_tioctl routines are specific to ncurses. They were not supported on Version 7, BSD or System V implementations. It - is recommended that any code depending on ncurses extensions be condi- - tioned using NCURSES_VERSION. + is recommended that any code depending on ncurses extensions be + conditioned using NCURSES_VERSION.
The putwin and getwin functions have several issues with portability: - o The files written and read by these functions use an implementa- - tion-specific format. Although the format is an obvious target for - standardization, it has been overlooked. + o The files written and read by these functions use an + implementation-specific format. Although the format is an obvious + target for standardization, it has been overlooked. Interestingly enough, according to the copyright dates in Solaris source, the functions (along with scr_init, etc.) originated with @@ -323,9 +342,9 @@ o the parameter is in the range 128-159, i.e., a C1 control code. If use_legacy_coding(3x) has been called with a 2 parameter, unctrl - returns the parameter, i.e., a one-character string with the param- - eter as the first character. Otherwise, it returns "~@", "~A", - etc., analogous to "^@", "^A", C0 controls. + returns the parameter, i.e., a one-character string with the + parameter as the first character. Otherwise, it returns "~@", + "~A", etc., analogous to "^@", "^A", C0 controls. X/Open Curses does not document whether unctrl can be called before initializing curses. This implementation permits that, and returns @@ -336,42 +355,43 @@ The strings returned by unctrl in this implementation are determined at compile time, showing C1 controls from the upper-128 codes with a "~" - prefix rather than "^". Other implementations have different conven- - tions. For example, they may show both sets of control characters with - "^", and strip the parameter to 7 bits. Or they may ignore C1 controls - and treat all of the upper-128 codes as printable. This implementation - uses 8 bits but does not modify the string to reflect locale. The - use_legacy_coding(3x) function allows the caller to change the output - of unctrl. + prefix rather than "^". Other implementations have different + conventions. For example, they may show both sets of control + characters with "^", and strip the parameter to 7 bits. Or they may + ignore C1 controls and treat all of the upper-128 codes as printable. + This implementation uses 8 bits but does not modify the string to + reflect locale. The use_legacy_coding(3x) function allows the caller + to change the output of unctrl. Likewise, the meta(3x) function allows the caller to change the output of keyname, i.e., it determines whether to use the "M-" prefix for - "meta" keys (codes in the range 128 to 255). Both use_legacy_cod- - ing(3x) and meta(3x) succeed only after curses is initialized. X/Open - Curses does not document the treatment of codes 128 to 159. When - treating them as "meta" keys (or if keyname is called before initializ- - ing curses), this implementation returns strings "M-^@", "M-^A", etc. + "meta" keys (codes in the range 128 to 255). Both + use_legacy_coding(3x) and meta(3x) succeed only after curses is + initialized. X/Open Curses does not document the treatment of codes + 128 to 159. When treating them as "meta" keys (or if keyname is called + before initializing curses), this implementation returns strings + "M-^@", "M-^A", etc. X/Open Curses documents unctrl as declared in <unctrl.h>, which ncurses - does. However, ncurses' <curses.h> includes <unctrl.h>, matching the + does. However, ncurses' <curses.h> includes <unctrl.h>, matching the behavior of SVr4 curses. Other implementations may not do that.
- If ncurses is configured to provide the sp-functions extension, the - state of use_env and use_tioctl may be updated before creating each - screen rather than once only (curs_sp_funcs(3x)). This feature of + If ncurses is configured to provide the sp-functions extension, the + state of use_env and use_tioctl may be updated before creating each + screen rather than once only (curs_sp_funcs(3x)). This feature of use_env is not provided by other implementations of curses.
- curses(3x), curs_initscr(3x), curs_inopts(3x), curs_kernel(3x), - curs_scr_dump(3x), curs_sp_funcs(3x), curs_variables(3x), legacy_cod- - ing(3x). + curses(3x), curs_initscr(3x), curs_inopts(3x), curs_kernel(3x), + curs_scr_dump(3x), curs_sp_funcs(3x), curs_variables(3x), + legacy_coding(3x) -ncurses 6.4 2023-08-05 curs_util(3x) +ncurses 6.4 2023-10-14 curs_util(3x)