X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_util.3x;fp=man%2Fcurs_util.3x;h=931a2766fb30a062bead0b6a670aa4862c86bc5c;hp=f833803a412dca6c3df227646d1acbf130438af1;hb=74433bcf4f6fe40862a28f3c00edaedcd5054b01;hpb=e6bb3226cdd35f5fd9f45bb1685cc2203c889480 diff --git a/man/curs_util.3x b/man/curs_util.3x index f833803a..931a2766 100644 --- a/man/curs_util.3x +++ b/man/curs_util.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright 2018-2019,2020 Thomas E. Dickey * +.\" Copyright 2018-2020,2021 Thomas E. Dickey * .\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,7 +28,7 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_util.3x,v 1.60 2020/12/19 22:44:46 tom Exp $ +.\" $Id: curs_util.3x,v 1.64 2021/12/25 22:05:53 tom Exp $ .TH curs_util 3X "" .ie \n(.g .ds `` \(lq .el .ds `` `` @@ -41,72 +41,72 @@ .na .hy 0 .SH NAME -\fBdelay_output\fR, -\fBfilter\fR, -\fBflushinp\fR, -\fBgetwin\fR, -\fBkey_name\fR, -\fBkeyname\fR, -\fBnofilter\fR, -\fBputwin\fR, -\fBunctrl\fR, -\fBuse_env\fR, -\fBuse_tioctl\fR, -\fBwunctrl\fR \- miscellaneous \fBcurses\fR utility routines +\fBdelay_output\fP, +\fBfilter\fP, +\fBflushinp\fP, +\fBgetwin\fP, +\fBkey_name\fP, +\fBkeyname\fP, +\fBnofilter\fP, +\fBputwin\fP, +\fBunctrl\fP, +\fBuse_env\fP, +\fBuse_tioctl\fP, +\fBwunctrl\fP \- miscellaneous \fBcurses\fP utility routines .ad .hy .SH SYNOPSIS -\fB#include \fR +\fB#include \fP .sp -\fBconst char *unctrl(chtype \fP\fIc\fP\fB);\fR +\fBconst char *unctrl(chtype \fP\fIc\fP\fB);\fP .br -\fBwchar_t *wunctrl(cchar_t *\fP\fIc\fP\fB);\fR +\fBwchar_t *wunctrl(cchar_t *\fP\fIc\fP\fB);\fP .sp -\fBconst char *keyname(int \fP\fIc\fP\fB);\fR +\fBconst char *keyname(int \fP\fIc\fP\fB);\fP .br -\fBconst char *key_name(wchar_t \fP\fIw\fP\fB);\fR +\fBconst char *key_name(wchar_t \fP\fIw\fP\fB);\fP .sp -\fBvoid filter(void);\fR +\fBvoid filter(void);\fP .br -\fBvoid nofilter(void);\fR +\fBvoid nofilter(void);\fP .sp -\fBvoid use_env(bool \fP\fIf\fP\fB);\fR +\fBvoid use_env(bool \fP\fIf\fP\fB);\fP .br -\fBvoid use_tioctl(bool \fP\fIf\fP\fB);\fR +\fBvoid use_tioctl(bool \fP\fIf\fP\fB);\fP .sp -\fBint putwin(WINDOW *\fP\fIwin\fP\fB, FILE *\fP\fIfilep\fP\fB);\fR +\fBint putwin(WINDOW *\fP\fIwin\fP\fB, FILE *\fP\fIfilep\fP\fB);\fP .br -\fBWINDOW *getwin(FILE *\fP\fIfilep\fP\fB);\fR +\fBWINDOW *getwin(FILE *\fP\fIfilep\fP\fB);\fP .sp -\fBint delay_output(int \fP\fIms\fP\fB);\fR +\fBint delay_output(int \fP\fIms\fP\fB);\fP .br -\fBint flushinp(void);\fR +\fBint flushinp(void);\fP .br .SH DESCRIPTION .SS unctrl .PP -The \fBunctrl\fR routine returns a character string which is a printable -representation of the character \fIc\fR, ignoring attributes. -Control characters are displayed in the \fB^\fR\fIX\fR notation. +The \fBunctrl\fP routine returns a character string which is a printable +representation of the character \fIc\fP, ignoring attributes. +Control characters are displayed in the \fB^\fP\fIX\fP notation. Printing characters are displayed as is. -The corresponding \fBwunctrl\fR returns a printable representation of +The corresponding \fBwunctrl\fP returns a printable representation of a wide character. .SS keyname/key_name .PP -The \fBkeyname\fR routine returns a character string -corresponding to the key \fIc\fR: +The \fBkeyname\fP routine returns a character string +corresponding to the key \fIc\fP: .bP Printable characters are displayed as themselves, e.g., a one-character string containing the key. .bP -Control characters are displayed in the \fB^\fR\fIX\fR notation. +Control characters are displayed in the \fB^\fP\fIX\fP notation. .bP DEL (character 127) is displayed as \fB^?\fP. .bP Values above 128 are either meta characters (if the screen has not been initialized, or if \fBmeta\fP(3X) has been called with a \fBTRUE\fP parameter), -shown in the \fBM\-\fR\fIX\fR notation, +shown in the \fBM\-\fP\fIX\fP notation, or are displayed as themselves. In the latter case, the values may not be printable; this follows the X/Open specification. @@ -118,31 +118,31 @@ to denote an error. X/Open also lists an \*(``UNKNOWN KEY\*('' return value, which some implementations return rather than null. .LP -The corresponding \fBkey_name\fR returns a character string corresponding -to the wide-character value \fIw\fR. +The corresponding \fBkey_name\fP returns a character string corresponding +to the wide-character value \fIw\fP. The two functions do not return the same set of strings; the latter returns null where the former would display a meta character. .SS filter/nofilter .PP -The \fBfilter\fR routine, if used, must be called before \fBinitscr\fR or -\fBnewterm\fR are called. +The \fBfilter\fP routine, if used, must be called before \fBinitscr\fP or +\fBnewterm\fP are called. Calling \fBfilter\fP causes these changes in initialization: .bP -\fBLINES\fR is set to 1; +\fBLINES\fP is set to 1; .bP the capabilities -\fBclear\fR, -\fBcud1\fR, -\fBcud\fR, -\fBcup\fR, -\fBcuu1\fR, -\fBcuu\fR, -\fBvpa\fR +\fBclear\fP, +\fBcud1\fP, +\fBcud\fP, +\fBcup\fP, +\fBcuu1\fP, +\fBcuu\fP, +\fBvpa\fP are disabled; .bP the capability \fBed\fP is disabled if \fBbce\fP is set; .bP -and the \fBhome\fR string is set to the value of \fBcr\fR. +and the \fBhome\fP string is set to the value of \fBcr\fP. .PP The \fBnofilter\fP routine cancels the effect of a preceding \fBfilter\fP call. @@ -152,9 +152,9 @@ The limitation arises because the \fBfilter\fP routine modifies the in-memory copy of the terminal information. .SS use_env .PP -The \fBuse_env\fR routine, if used, -should be called before \fBinitscr\fR or -\fBnewterm\fR are called +The \fBuse_env\fP routine, if used, +should be called before \fBinitscr\fP or +\fBnewterm\fP are called (because those compute the screen size). It modifies the way \fBncurses\fP treats environment variables when determining the screen size. @@ -170,22 +170,22 @@ If successful, it overrides the values from the terminal database. .bP Finally (unless \fBuse_env\fP was called with \fBFALSE\fP parameter), -\fBncurses\fP examines the \fBLINES\fR or \fBCOLUMNS\fR environment variables, +\fBncurses\fP examines the \fBLINES\fP or \fBCOLUMNS\fP environment variables, using a value in those to override the results from the operating system or terminal database. .IP \fBNcurses\fP also updates the screen size in response to \fBSIGWINCH\fP, -unless overridden by the \fBLINES\fR or \fBCOLUMNS\fR environment variables, +unless overridden by the \fBLINES\fP or \fBCOLUMNS\fP environment variables, .SS use_tioctl .PP -The \fBuse_tioctl\fR routine, if used, -should be called before \fBinitscr\fR or \fBnewterm\fR are called +The \fBuse_tioctl\fP routine, if used, +should be called before \fBinitscr\fP or \fBnewterm\fP are called (because those compute the screen size). -After \fBuse_tioctl\fR is called with \fBTRUE\fR as an argument, +After \fBuse_tioctl\fP is called with \fBTRUE\fP as an argument, \fBncurses\fP modifies the last step in its computation of screen size as follows: .bP -checks if the \fBLINES\fR and \fBCOLUMNS\fR environment variables +checks if the \fBLINES\fP and \fBCOLUMNS\fP environment variables are set to a number greater than zero. .bP for each, \fBncurses\fP updates the corresponding environment variable @@ -202,7 +202,7 @@ center tab(/); l l l _ _ _ lw7 lw7 lw40. -\fIuse_env\fR/\fIuse_tioctl\fR/\fISummary\fR +\fBuse_env\fP/\fBuse_tioctl\fP/\fBSummary\fP TRUE/FALSE/T{ This is the default behavior. \fBncurses\fP uses operating system calls @@ -221,14 +221,14 @@ T} .TE .SS putwin/getwin .PP -The \fBputwin\fR routine writes all data associated -with window (or pad) \fIwin\fR into -the file to which \fIfilep\fR points. +The \fBputwin\fP routine writes all data associated +with window (or pad) \fIwin\fP into +the file to which \fIfilep\fP points. This information can be later retrieved -using the \fBgetwin\fR function. +using the \fBgetwin\fP function. .PP -The \fBgetwin\fR routine reads window related data stored in the file by -\fBputwin\fR. +The \fBgetwin\fP routine reads window related data stored in the file by +\fBputwin\fP. The routine then creates and initializes a new window using that data. It returns a pointer to the new window. @@ -250,28 +250,28 @@ created in the application using \fBinit_pair\fP, they will not be colored when the window is refreshed. .SS delay_output .PP -The \fBdelay_output\fR routine inserts an \fIms\fR millisecond pause +The \fBdelay_output\fP routine inserts an \fIms\fP 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 specified, -this uses \fBnapms\fR to perform the delay. +this uses \fBnapms\fP to perform the delay. .SS flushinp .PP -The \fBflushinp\fR routine throws away any typeahead that has been typed by the +The \fBflushinp\fP routine throws away any typeahead that has been typed by the user and has not yet been read by the program. .SH RETURN VALUE -Except for \fBflushinp\fR, routines that return an integer return \fBERR\fR -upon failure and \fBOK\fR (SVr4 specifies only "an integer value other than -\fBERR\fR") upon successful completion. +Except for \fBflushinp\fP, routines that return an integer return \fBERR\fP +upon failure and \fBOK\fP (SVr4 specifies only "an integer value other than +\fBERR\fP") upon successful completion. .PP -Routines that return pointers return \fBNULL\fR on error. +Routines that return pointers return \fBNULL\fP on error. .PP X/Open does not define any error conditions. In this implementation .RS 3 .TP 5 -\fBflushinp\fR +\fBflushinp\fP returns an error if the terminal was not initialized. .TP 5 \fBputwin\fP @@ -280,10 +280,10 @@ returns an error if the associated \fBfwrite\fP calls return an error. .SH PORTABILITY .SS filter .PP -The SVr4 documentation describes the action of \fBfilter\fR only in the vaguest +The SVr4 documentation describes the action of \fBfilter\fP only in the vaguest terms. The description here is adapted from the XSI Curses standard (which -erroneously fails to describe the disabling of \fBcuu\fR). +erroneously fails to describe the disabling of \fBcuu\fP). .SS keyname .PP The \fBkeyname\fP function may return the names of user-defined @@ -302,7 +302,7 @@ The \fBnofilter\fP and \fBuse_tioctl\fP routines are specific to \fBncurses\fP. They were not supported on Version 7, BSD or System V implementations. It is recommended that any code depending on \fBncurses\fP extensions be conditioned using NCURSES_VERSION. -.SS putwin/getwin +.SS putwin/getwin file-format .PP The \fBputwin\fP and \fBgetwin\fP functions have several issues with portability: @@ -336,7 +336,7 @@ However, reading from a file written using mixed schemes may not be successful. .SS unctrl/wunctrl .PP The XSI Curses standard, Issue 4 describes these functions. -It states that \fBunctrl\fR and \fBwunctrl\fR will return a null pointer if +It states that \fBunctrl\fP and \fBwunctrl\fP will return a null pointer if unsuccessful, but does not define any error conditions. This implementation checks for three cases: .bP @@ -358,7 +358,7 @@ and returns the \*(``~@\*('', etc., values in that case. parameter values outside the 0 to 255 range. \fBunctrl\fP returns a null pointer. .PP -The strings returned by \fBunctrl\fR in this implementation are determined +The strings returned by \fBunctrl\fP in this implementation are determined at compile time, showing C1 controls from the upper-128 codes with a \*(``~\*('' prefix rather than \*(``^\*(''. @@ -393,15 +393,15 @@ Other implementations may not do that. If \fBncurses\fP is configured to provide the sp-functions extension, the state of \fBuse_env\fP and \fBuse_tioctl\fP may be updated before creating each \fIscreen\fP rather than once only -(\fBcurs_sp_funcs\fR(3X)). +(\fBcurs_sp_funcs\fP(3X)). This feature of \fBuse_env\fP is not provided by other implementation of curses. .SH SEE ALSO -\fBcurses\fR(3X), -\fBcurs_initscr\fR(3X), -\fBcurs_inopts\fR(3X), -\fBcurs_kernel\fR(3X), -\fBcurs_scr_dump\fR(3X), -\fBcurs_sp_funcs\fR(3X), -\fBcurs_variables\fR(3X), -\fBlegacy_coding\fR(3X). +\fBcurses\fP(3X), +\fBcurs_initscr\fP(3X), +\fBcurs_inopts\fP(3X), +\fBcurs_kernel\fP(3X), +\fBcurs_scr_dump\fP(3X), +\fBcurs_sp_funcs\fP(3X), +\fBcurs_variables\fP(3X), +\fBlegacy_coding\fP(3X).