X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;ds=sidebyside;f=man%2Fcurs_terminfo.3x;h=9cdbbddf5c07f25202265537eeb49c7b7b7f2b78;hb=HEAD;hp=6fdc89991a7c79fc807bee53fe4bfaf74dd5cc52;hpb=bd2d9c5734d2c66abe0b2ddd766695b200c154fe;p=ncurses.git

diff --git a/man/curs_terminfo.3x b/man/curs_terminfo.3x
index 6fdc8999..6dcfc8b8 100644
--- a/man/curs_terminfo.3x
+++ b/man/curs_terminfo.3x
@@ -28,8 +28,8 @@
 .\" 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.144 2024/09/14 20:06:50 tom Exp $
+.TH curs_terminfo 3X 2024-09-14 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq
@@ -48,7 +48,6 @@
 .
 .SH NAME
 \fB\%del_curterm\fP,
-\fB\%mvcur\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 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);
@@ -228,7 +225,7 @@ initializing the
 .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
@@ -250,9 +247,9 @@ terminal,
 passing an output
 .I stream
 rather than a
-.I descriptor.
+.IR descriptor .
 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
@@ -267,7 +264,7 @@ then \fB\%setupterm\fP returns
 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
@@ -333,63 +330,82 @@ which uses all the defaults and sends the output to
 .RE
 .\" ********************************************************************
 .SS "The Terminal State"
-\fB\%setupterm\fP stores its information about the terminal in a
+.B \%setupterm
+stores its information about the terminal in a
 .I \%TERMINAL
-structure pointed to by the global variable \fB\%cur_term\fP.
+structure pointed to by the global variable
+.BR \%cur_term "."
 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.
-.PP
-If \fB\%setupterm\fP 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,
-\fB\%setupterm\fP allocates new storage for each set of terminal
-capabilities.
+making it unavailable to applications.
 .PP
-\fB\%set_curterm\fP sets \fB\%cur_term\fP to
-.I \%nterm,
-and makes all of the
+If
+.B \%setupterm
+is called repeatedly for the same terminal type,
+it reuses the information.
+It maintains only one copy of a given type's capabilities in memory.
+If called for different types,
+.B \%setupterm
+allocates new storage for each set of terminal capabilities.
+.PP
+.B \%set_curterm
+sets
+.B \%cur_term
+to
+.IR \%nterm ","
+making all of the
 .I \%term\%info
 Boolean,
 numeric,
-and string variables use the values from
-.I \%nterm.
-It returns the old value of \fB\%cur_term\fP.
-.PP
-\fB\%del_curterm\fP frees the space pointed to by
-.I \%oterm
-and makes it available for further use.
+and string capabilities use the values from
+.IR \%nterm "."
+It returns the old value of
+.BR \%cur_term "."
+.PP
+.B \%del_curterm
+frees the memory pointed to by
+.BR \%oterm ","
+making it available for further use.
 If
-.I \%oterm
+.B \%oterm
 is
-the same as \fB\%cur_term\fP,
+the same as
+.BR \%cur_term ","
 references to any of the
 .I \%term\%info
 Boolean,
 numeric,
-and string variables thereafter may refer to invalid memory locations
-until another \fB\%setupterm\fP has been called.
-.PP
-\fB\%restartterm\fP is similar to \fB\%setupterm\fP and \fB\%initscr\fP,
-except that it is called after restoring memory to a previous state
+and string capabilities thereafter may refer to invalid memory locations
+until
+.B \%setupterm
+is called again.
+.PP
+.B \%restartterm
+is similar to
+.BR \%setupterm ","
+but is intended for use after restoring program memory
+to a previous state
 (for example,
-when reloading a game saved as a core image dump).
-\fB\%restartterm\fP 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.
+when reloading an application that has been suspended from one terminal
+session and restored in another).
+.B \%restartterm
+assumes that the display dimensions
+and the input and output options are the same as when memory was saved,
+but the terminal type and line speed may differ.
 Accordingly,
-\fB\%restartterm\fP saves various terminal state bits,
-calls \fB\%setupterm\fP,
-and then restores the bits.
+.B \%restartterm
+saves relevant terminal state,
+calls
+.BR \%setupterm ","
+then restores that state.
 .\" ********************************************************************
 .SS "Formatting Output"
 \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.
@@ -419,7 +435,7 @@ rather than a fixed-parameter list.
 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.
@@ -463,17 +479,9 @@ The
 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,
@@ -503,12 +511,12 @@ specified in \fB\%setupterm\fP.
 .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
-.I putc.
+.IR putc .
 .PP
 \fB\%vidattr\fP is like \fB\%vidputs\fP,
 except that it outputs through \fI\%putchar\fP(3).
@@ -525,14 +533,14 @@ They use multiple parameters to represent the character attributes and
 color;
 namely,
 .bP
-.I \%attrs,
+.IR \%attrs ,
 of type
-.I \%attr_t,
+.IR \%attr_t ,
 for the attributes and
 .bP
-.I pair,
+.IR pair ,
 of type
-.I short,
+.IR short ,
 for the color pair number.
 .PP
 Use the attribute constants prefixed with
@@ -548,21 +556,11 @@ argument for future use,
 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
-declares them in
+declares it in
 .I \%curses.h
 because System\ V did this
 (see section \*(``HISTORY\*('' below).
@@ -573,7 +571,7 @@ because System\ V did this
 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.
@@ -686,7 +684,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
-.I \%ncurses,
+.IR \%ncurses ,
 .TP 5
 .B del_curtem
 fails if its terminal parameter is null.
@@ -696,12 +694,13 @@ calls \fB\%tputs\fP,
 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
-.RB ( \%stdscr ,
+.RB \%( stdscr ,
 .BR \%curscr ,
 and
 .BR \%newscr )
@@ -739,7 +738,7 @@ is also provided in the non-wide-character configuration.
 .\" ********************************************************************
 .SH EXTENSIONS
 The functions marked as extensions were designed for
-.I \%ncurses,
+.IR \%ncurses ,
 and are not found in SVr4
 .IR curses ,
 4.4BSD
@@ -752,7 +751,7 @@ implementation.
 allows
 .I opts
 to be a pointer to
-.I int,
+.IR int ,
 which overrides the
 .I pair
 .RI ( short )
@@ -804,7 +803,7 @@ but is assumed by some applications.
 .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
@@ -826,7 +825,7 @@ did not allow a reliable way to clean up on receiving
 .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.
@@ -844,10 +843,12 @@ standardized in the late 1980s.
 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,
@@ -906,7 +907,9 @@ capabilities use string parameters
 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
@@ -938,15 +941,18 @@ the windows console driver by checking if \fB$TERM\fP is set to
 \*(``#win32con\*('' or an abbreviation of that string.
 .SS "Other Portability Issues"
 In SVr4,
-\fB\%set_curterm\fP returns an
-.I int,
+.I \%set_curterm
+returns an
+.IR int ","
 .B OK
 or
-.BR ERR .
+.BR ERR "."
 We have chosen to implement the X/Open Curses semantics.
 .PP
 In SVr4,
-the third argument of \fB\%tputs\fP has the type
+the third argument of
+.I \%tputs
+has the type
 .RB \*(`` "int (*putc)(char)" \*(''.
 .PP
 At least one implementation of X/Open Curses (Solaris) returns a value
@@ -954,70 +960,10 @@ other than
 .B OK
 or
 .B ERR
-from \fB\%tputs\fP.
+from
+.IR \%tputs "."
 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
@@ -1084,6 +1030,7 @@ by adding functions to retrieve capability values
 interface),
 and reusing \fB\%tgoto\fP and \fB\%tputs\fP.
 .PP
+.ne 4v
 .TS
 lB lB
 lB lx.