ncurses 6.5 - patch 20240615

[ncurses.git] / man / curs_terminfo.3x

diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x
index 6fdc89991a7c79fc807bee53fe4bfaf74dd5cc52..2c373f6f66c57fca30d794d22a8c18a33c73a5cc 100644 (file)
--- a/man/curs_terminfo.3x
+++ b/man/curs_terminfo.3x
@@ -28,8 +28,8 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_terminfo.3x,v 1.130 2024/02/24 20:04:09 tom Exp $
-.TH curs_terminfo 3X 2024-02-24 "ncurses 6.4" "Library calls"
+.\" $Id: curs_terminfo.3x,v 1.142 2024/06/08 23:05:52 tom Exp $
+.TH curs_terminfo 3X 2024-06-08 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"

 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq
 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq


@@ -48,7 +48,6 @@
 .
 .SH NAME
 \fB\%del_curterm\fP,
 .
 .SH NAME
 \fB\%del_curterm\fP,

-\fB\%mvcur\fP,

 \fB\%putp\fP,
 \fB\%restartterm\fP,
 \fB\%set_curterm\fP,
 \fB\%putp\fP,
 \fB\%restartterm\fP,
 \fB\%set_curterm\fP,


@@ -100,8 +99,6 @@
 \fBint vid_puts(attr_t \fIattrs\fP, short \fIpair\fP, void *\fIopts\fP, int (*\fIputc\fP)(int));
 \fBint vid_attr(attr_t \fIattrs\fP, short \fIpair\fP, void *\fIopts\fP);
 .PP
 \fBint vid_puts(attr_t \fIattrs\fP, short \fIpair\fP, void *\fIopts\fP, int (*\fIputc\fP)(int));
 \fBint vid_attr(attr_t \fIattrs\fP, short \fIpair\fP, void *\fIopts\fP);
 .PP

-\fBint mvcur(int \fIoldrow\fP, int \fIoldcol\fP, int \fInewrow\fP, int \fInewcol\fP);
-.PP

 \fBint tigetflag(const char *\fIcap-code\fP);
 \fBint tigetnum(const char *\fIcap-code\fP);
 \fBchar *tigetstr(const char *\fIcap-code\fP);
 \fBint tigetflag(const char *\fIcap-code\fP);
 \fBint tigetnum(const char *\fIcap-code\fP);
 \fBchar *tigetstr(const char *\fIcap-code\fP);


@@ -228,7 +225,7 @@ initializing the
 .I \%term\%info
 structures,
 but does not set up the output virtualization structures used by
 .I \%term\%info
 structures,
 but does not set up the output virtualization structures used by

-.I curses.
+.IR curses .

 Its parameters follow.
 .RS 3
 .TP 5
 Its parameters follow.
 .RS 3
 .TP 5


@@ -250,9 +247,9 @@ terminal,
 passing an output
 .I stream
 rather than a
 passing an output
 .I stream
 rather than a

-.I descriptor.
+.IR descriptor .

 In
 In

-.I curses,
+.IR curses ,

 the two are the same because \fB\%newterm\fP calls \fB\%setupterm\fP,
 passing the file descriptor derived from its output stream parameter.
 .TP 5
 the two are the same because \fB\%newterm\fP calls \fB\%setupterm\fP,
 passing the file descriptor derived from its output stream parameter.
 .TP 5


@@ -267,7 +264,7 @@ then \fB\%setupterm\fP returns
 or
 .B ERR
 and stores a status value in the integer pointed to by
 or
 .B ERR
 and stores a status value in the integer pointed to by

-.I errret.
+.IR errret .

 A return value of
 .B OK
 combined with status of
 A return value of
 .B OK
 combined with status of


@@ -350,13 +347,13 @@ If it is called for different terminal types,
 capabilities.
 .PP
 \fB\%set_curterm\fP sets \fB\%cur_term\fP to
 capabilities.
 .PP
 \fB\%set_curterm\fP sets \fB\%cur_term\fP to

-.I \%nterm,
+.IR \%nterm ,

 and makes all of the
 .I \%term\%info
 Boolean,
 numeric,
 and string variables use the values from
 and makes all of the
 .I \%term\%info
 Boolean,
 numeric,
 and string variables use the values from

-.I \%nterm.
+.IR \%nterm .

 It returns the old value of \fB\%cur_term\fP.
 .PP
 \fB\%del_curterm\fP frees the space pointed to by
 It returns the old value of \fB\%cur_term\fP.
 .PP
 \fB\%del_curterm\fP frees the space pointed to by


@@ -389,7 +386,7 @@ and then restores the bits.
 \fB\%tparm\fP instantiates the string
 .I str
 with parameters
 \fB\%tparm\fP instantiates the string
 .I str
 with parameters

-.I pi.
+.IR pi .

 A pointer is returned to the result of
 .I str
 with the parameters applied.
 A pointer is returned to the result of
 .I str
 with the parameters applied.


@@ -419,7 +416,7 @@ rather than a fixed-parameter list.
 Its numeric parameters are
 .IR int s
 rather than
 Its numeric parameters are
 .IR int s
 rather than

-.IR long s.
+.IR long "s."

 .PP
 Both \fB\%tparm\fP and \fB\%tiparm\fP assume that the application passes
 parameters consistent with the terminal description.
 .PP
 Both \fB\%tparm\fP and \fB\%tiparm\fP assume that the application passes
 parameters consistent with the terminal description.


@@ -463,17 +460,9 @@ The
 parameter must be a
 .I \%term\%info
 string variable or the return value of
 parameter must be a
 .I \%term\%info
 string variable or the return value of

-\fB\%tparm\fP,
-\fB\%tiparm\fP,
-\fB\%tgetstr\fP,
-or \fB\%tgoto\fP.
-.IP
-The \fB\%tgetstr\fP and \fB\%tgoto\fP functions are part of the
-.I termcap
-interface,
-which happens to share these function names with the
-.I \%term\%info
-API.
+.B \%tparm
+or
+.BR \%tiparm "."

 .bP
 .I affcnt
 is the number of lines affected,
 .bP
 .I affcnt
 is the number of lines affected,


@@ -503,12 +492,12 @@ specified in \fB\%setupterm\fP.
 .PP
 \fB\%vidputs\fP displays the string on the terminal in the video
 attribute mode
 .PP
 \fB\%vidputs\fP displays the string on the terminal in the video
 attribute mode

-.I attrs,
+.IR attrs ,

 which is any combination of the attributes listed in \fB\%curses\fP(3X).
 The characters are passed to the
 .IR \%putchar -like
 function
 which is any combination of the attributes listed in \fB\%curses\fP(3X).
 The characters are passed to the
 .IR \%putchar -like
 function

-.I putc.
+.IR putc .

 .PP
 \fB\%vidattr\fP is like \fB\%vidputs\fP,
 except that it outputs through \fI\%putchar\fP(3).
 .PP
 \fB\%vidattr\fP is like \fB\%vidputs\fP,
 except that it outputs through \fI\%putchar\fP(3).


@@ -525,14 +514,14 @@ They use multiple parameters to represent the character attributes and
 color;
 namely,
 .bP
 color;
 namely,
 .bP

-.I \%attrs,
+.IR \%attrs ,

 of type
 of type

-.I \%attr_t,
+.IR \%attr_t ,

 for the attributes and
 .bP
 for the attributes and
 .bP

-.I pair,
+.IR pair ,

 of type
 of type

-.I short,
+.IR short ,

 for the color pair number.
 .PP
 Use the attribute constants prefixed with
 for the color pair number.
 .PP
 Use the attribute constants prefixed with


@@ -548,21 +537,11 @@ argument for future use,
 saying that applications must provide a null pointer for that argument;
 but see section \*(``EXTENSIONS\*('' below.
 .PP
 saying that applications must provide a null pointer for that argument;
 but see section \*(``EXTENSIONS\*('' below.
 .PP

-\fB\%mvcur\fP 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,
-\fB\%mvcur\fP uses an output file descriptor derived from
-the output stream parameter of \fB\%newterm\fP(3X).
-.PP
-While \fB\%putp\fP and \fB\%mvcur\fP are low-level functions that do not
-use high-level
+While \fB\%putp\fP is a low-level function that does not use high-level

 .I curses
 state,
 .I \%ncurses
 .I curses
 state,
 .I \%ncurses

-declares them in
+declares it in

 .I \%curses.h
 because System\ V did this
 (see section \*(``HISTORY\*('' below).
 .I \%curses.h
 because System\ V did this
 (see section \*(``HISTORY\*('' below).


@@ -573,7 +552,7 @@ because System\ V did this
 and \fB\%tigetstr\fP return the value of the capability corresponding to
 the
 .I \%term\%info
 and \fB\%tigetstr\fP return the value of the capability corresponding to
 the
 .I \%term\%info

-.I cap-code,
+.IR cap-code ,

 such as
 .BR xenl ,
 passed to them.
 such as
 .BR xenl ,
 passed to them.


@@ -686,7 +665,7 @@ but it is possible to do that using the \fB\%delscreen\fP(3X) function.
 .SH RETURN VALUE
 X/Open Curses defines no failure conditions.
 In
 .SH RETURN VALUE
 X/Open Curses defines no failure conditions.
 In

-.I \%ncurses,
+.IR \%ncurses ,

 .TP 5
 .B del_curtem
 fails if its terminal parameter is null.
 .TP 5
 .B del_curtem
 fails if its terminal parameter is null.


@@ -696,12 +675,13 @@ calls \fB\%tputs\fP,
 returning the same error codes.
 .TP 5
 .B restartterm
 returning the same error codes.
 .TP 5
 .B restartterm

-fails if the associated call to \fB\%setupterm\fP returns an error.
+fails if the associated call to \fB\%setupterm\fP returns
+.BR ERR "."

 .TP 5
 .B setupterm
 fails if it cannot allocate enough memory,
 or create the initial windows
 .TP 5
 .B setupterm
 fails if it cannot allocate enough memory,
 or create the initial windows

-.RB ( \%stdscr ,
+.RB \%( stdscr ,

 .BR \%curscr ,
 and
 .BR \%newscr )
 .BR \%curscr ,
 and
 .BR \%newscr )


@@ -739,7 +719,7 @@ is also provided in the non-wide-character configuration.
 .\" ********************************************************************
 .SH EXTENSIONS
 The functions marked as extensions were designed for
 .\" ********************************************************************
 .SH EXTENSIONS
 The functions marked as extensions were designed for

-.I \%ncurses,
+.IR \%ncurses ,

 and are not found in SVr4
 .IR curses ,
 4.4BSD
 and are not found in SVr4
 .IR curses ,
 4.4BSD


@@ -752,7 +732,7 @@ implementation.
 allows
 .I opts
 to be a pointer to
 allows
 .I opts
 to be a pointer to

-.I int,
+.IR int ,

 which overrides the
 .I pair
 .RI ( short )
 which overrides the
 .I pair
 .RI ( short )


@@ -804,7 +784,7 @@ but is assumed by some applications.
 .PP
 Other implementions may not declare the capability name arrays.
 Some provide them without declaring them.
 .PP
 Other implementions may not declare the capability name arrays.
 Some provide them without declaring them.

-X/Open does not specify them.
+X/Open Curses does not specify them.

 .PP
 Extended terminal capability names,
 as defined by
 .PP
 Extended terminal capability names,
 as defined by


@@ -826,7 +806,7 @@ did not allow a reliable way to clean up on receiving
 .PP
 The current version (ncurses6)
 uses output buffers managed directly by
 .PP
 The current version (ncurses6)
 uses output buffers managed directly by

-.I \%ncurses.
+.IR \%ncurses .

 Some of the low-level functions described in this manual page write
 to the standard output.
 They are not signal-safe.
 Some of the low-level functions described in this manual page write
 to the standard output.
 They are not signal-safe.


@@ -844,10 +824,12 @@ standardized in the late 1980s.
 X/Open Curses uses
 .I \%const
 less effectively than a later design might,
 X/Open Curses uses
 .I \%const
 less effectively than a later design might,

-in some cases applying it needlessly to values are already constant,
-and in most cases overlooking parameters which normally would use
-.I \%const.
-Using constant parameters for functions which do not use
+sometimes applying it needlessly to values that are already constant,
+and in most cases overlooking parameters that normally would use
+.IR \%const .
+Passing
+.IR \%const -qualified
+parameters to functions that do not declare them

 .I \%const
 may prevent the program from compiling.
 On the other hand,
 .I \%const
 may prevent the program from compiling.
 On the other hand,


@@ -906,7 +888,9 @@ capabilities use string parameters
 the ones used for programmable function keys).
 .IP
 The \fI\%ncurses\fP library checks usage of these capabilities,
 the ones used for programmable function keys).
 .IP
 The \fI\%ncurses\fP library checks usage of these capabilities,

-and returns an error if the capability mishandles string parameters.
+and returns
+.B ERR
+if the capability mishandles string parameters.

 But it cannot check if a calling program provides strings in the right
 places for the \fB\%tparm\fP calls.
 .IP
 But it cannot check if a calling program provides strings in the right
 places for the \fB\%tparm\fP calls.
 .IP


@@ -939,7 +923,7 @@ the windows console driver by checking if \fB$TERM\fP is set to
 .SS "Other Portability Issues"
 In SVr4,
 \fB\%set_curterm\fP returns an
 .SS "Other Portability Issues"
 In SVr4,
 \fB\%set_curterm\fP returns an

-.I int,
+.IR int ,

 .B OK
 or
 .BR ERR .
 .B OK
 or
 .BR ERR .


@@ -957,67 +941,6 @@ or
 from \fB\%tputs\fP.
 It instead returns the length of the string,
 and does no error checking.
 from \fB\%tputs\fP.
 It instead returns the length of the string,
 and does no error checking.

-.PP
-X/Open Curses notes that after calling \fB\%mvcur\fP,
-the
-.I curses
-state may not match the actual terminal state,
-and that an application should touch and refresh the window before
-resuming normal
-.I curses
-calls.
-Both
-.I \%ncurses
-and SVr4
-.I curses
-implement \fB\%mvcur\fP using the
-.I SCREEN
-data allocated in either \fB\%initscr\fP or \fB\%newterm\fP.
-So though it is documented as a
-.I \%term\%info
-function,
-\fB\%mvcur\fP is really a
-.I curses
-function that is not well specified.
-.PP
-X/Open notes that after calling \fB\%mvcur\fP,
-the
-.I curses
-state may not match the actual terminal state,
-and that an application should touch and refresh the window before
-resuming normal
-.I curses
-calls.
-Both
-.I \%ncurses
-and SVr4
-.I curses
-implement \fB\%mvcur\fP using the
-.I SCREEN
-data allocated in either \fB\%initscr\fP or \fB\%newterm\fP.
-So though it is documented as a
-.I \%term\%info
-function,
-\fB\%mvcur\fP is really a
-.I curses
-function that is not well specified.
-.PP
-X/Open Curses states that the old location must be given for
-\fB\%mvcur\fP to accommodate terminals that lack absolute cursor
-positioning.
-.\" X/Open Curses Issue 7, p. 161
-.I \%ncurses
-allows the caller to use \-1 for either or both old coordinates.
-The \-1 tells
-.I \%ncurses
-that the old location is unknown,
-and that it must use only absolute motion,
-as with the
-.B \%cursor_address
-.RB ( cup )
-capability,
-rather than the least costly combination of absolute and relative
-motion.

 .\" ********************************************************************
 .SH HISTORY
 SVr2 (1984) introduced the
 .\" ********************************************************************
 .SH HISTORY
 SVr2 (1984) introduced the


@@ -1084,6 +1007,7 @@ by adding functions to retrieve capability values
 interface),
 and reusing \fB\%tgoto\fP and \fB\%tputs\fP.
 .PP
 interface),
 and reusing \fB\%tgoto\fP and \fB\%tputs\fP.
 .PP

+.ne 4v

 .TS
 lB lB
 lB lx.
 .TS
 lB lB
 lB lx.