.\"***************************************************************************
-.\" Copyright 2018-2021,2022 Thomas E. Dickey *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_kernel.3x,v 1.33 2022/02/12 20:05:11 tom Exp $
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $Id: curs_kernel.3x,v 1.65 2024/06/08 21:00:58 tom Exp $
+.TH curs_kernel 3X 2024-06-08 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
..
-.TH curs_kernel 3X 2022-02-12 "ncurses 6.4" "Library calls"
-.na
-.hy 0
.SH NAME
-\fBdef_prog_mode\fP,
-\fBdef_shell_mode\fP,
-\fBreset_prog_mode\fP,
-\fBreset_shell_mode\fP,
-\fBresetty\fP,
-\fBsavetty\fP,
-\fBgetsyx\fP,
-\fBsetsyx\fP,
-\fBripoffline\fP,
-\fBcurs_set\fP,
-\fBnapms\fP \- low-level \fBcurses\fP routines
-.ad
-.hy
+\fB\%def_prog_mode\fP,
+\fB\%def_shell_mode\fP,
+\fB\%reset_prog_mode\fP,
+\fB\%reset_shell_mode\fP,
+\fB\%resetty\fP,
+\fB\%savetty\fP,
+\fB\%getsyx\fP,
+\fB\%setsyx\fP,
+\fB\%curs_set\fP,
+\fB\%mvcur\fP,
+\fB\%napms\fP,
+\fB\%ripoffline\fP \-
+low-level \fIcurses\fR routines
.SH SYNOPSIS
-\fB#include <curses.h>\fP
-.sp
-\fBint def_prog_mode(void);\fP
-.br
-\fBint def_shell_mode(void);\fP
-.sp
-\fBint reset_prog_mode(void);\fP
-.br
-\fBint reset_shell_mode(void);\fP
-.sp
-\fBint resetty(void);\fP
-.br
-\fBint savetty(void);\fP
-.sp
-\fBvoid getsyx(int \fIy\fB, int \fIx\fB);\fR
-.br
-\fBvoid setsyx(int \fIy\fB, int \fIx\fB);\fR
-.sp
-\fBint ripoffline(int \fIline\fB, int (*\fIinit\fB)(WINDOW *, int));\fR
-.br
-\fBint curs_set(int \fIvisibility\fB);\fR
-.br
-\fBint napms(int \fIms\fB);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint def_prog_mode(void);
+\fBint def_shell_mode(void);
+.PP
+\fBint reset_prog_mode(void);
+\fBint reset_shell_mode(void);
+.PP
+\fBint resetty(void);
+\fBint savetty(void);
+.PP
+\fBvoid getsyx(int \fIy\fP, int \fIx\fP);
+\fBvoid setsyx(int \fIy\fP, int \fIx\fP);
+.PP
+\fBint curs_set(int \fIvisibility\fP);
+\fBint mvcur(int \fIoldrow\fP, int \fIoldcol\fP, int \fInewrow\fP, int \fInewcol\fP);
+\fBint napms(int \fIms\fP);
+\fBint ripoffline(int \fIline\fP, int (*\fIinit\fP)(WINDOW *, int));
+.fi
.SH DESCRIPTION
The following routines give low-level access
to various \fBcurses\fP capabilities.
These routines typically are used inside library routines.
-.SS def_prog_mode, def_shell_mode
-.PP
+.SS "def_prog_mode, def_shell_mode"
The \fBdef_prog_mode\fP and \fBdef_shell_mode\fP routines save the
-current terminal modes as the \*(``program\*('' (in \fBcurses\fP) or \*(``shell\*(''
+current terminal modes as the \*(``program\*(''
+(in \fBcurses\fP) or \*(``shell\*(''
(not in \fBcurses\fP) state for use by the \fBreset_prog_mode\fP and
\fBreset_shell_mode\fP routines.
This is done automatically by \fBinitscr\fP.
There is one such save area for each screen context
allocated by \fBnewterm\fP.
-.SS reset_prog_mode, reset_shell_mode
-.PP
+.SS "reset_prog_mode, reset_shell_mode"
The \fBreset_prog_mode\fP and \fBreset_shell_mode\fP routines restore
the terminal to \*(``program\*('' (in \fBcurses\fP) or \*(``shell\*('' (out of
\fBcurses\fP) state.
These are done automatically by \fBendwin\fP(3X) and,
after an \fBendwin\fP, by \fBdoupdate\fP,
so they normally are not called.
-.SS resetty, savetty
-.PP
+.SS "resetty, savetty"
The \fBresetty\fP and \fBsavetty\fP routines save and restore the
state of the terminal modes.
\fBsavetty\fP saves the current state in
a buffer and \fBresetty\fP restores the state to what it was at the
last call to \fBsavetty\fP.
.SS getsyx
+.B \%getsyx
+stores the coordinates of virtual screen
+.RB \%( newscr )
+cursor in
+.I y
+and
+.IR x "."
+If
+.BR \%newscr 's
+\fB\%leaveok\fP(3X) output option is
+.BR TRUE ","
+.B \%getsyx
+stores
+.B \-1
+in both
+.I y
+and
+.IR x "."
+If lines have been removed from the top of the screen using
+.BR \%ripoffline ","
+.I y
+includes these lines;
+therefore,
+.I y
+and
+.I x
+populated by
+.B \%getsyx
+should be used only as arguments for
+.BR \%setsyx "."
.PP
-The \fBgetsyx\fP routine returns the current coordinates
-of the \fIvirtual screen\fP cursor in \fIy\fP and \fIx\fP.
-If \fBleaveok\fP is currently \fBTRUE\fP, then
-\fB\-1\fP,\fB\-1\fP is returned.
-If lines have been removed from the top of the
-screen, using \fBripoffline\fP, \fIy\fP and \fIx\fP include these lines;
-therefore, \fIy\fP and \fIx\fP should be used only as arguments for
-\fBsetsyx\fP.
-.PP
-Few applications will use this feature,
-most use \fBgetyx\fP instead.
+Few applications use this feature;
+most call \fB\%getyx\fP(3X) instead.
.SS setsyx
+.B \%setsyx
+sets the virtual screen
+.RB \%( newscr )
+cursor location to
+.RI ( y ,
+.IR x ")."
+.B "\%setsyx(\-1, \-1)"
+is equivalent to
+.BR "\%leaveok(newscr, TRUE)" "."
.PP
-The \fBsetsyx\fP routine sets
-the \fIvirtual screen\fP cursor to \fIy\fP, \fIx\fP.
-If \fIy\fP and \fIx\fP are both \fB\-1\fP, then
-\fBleaveok\fP is set.
-The two routines \fBgetsyx\fP and \fBsetsyx\fP
-are designed to be used by a library routine, which manipulates
-\fBcurses\fP windows but does not want to change the current position
-of the program's cursor.
-The library routine would call \fBgetsyx\fP
-at the beginning, do its manipulation of its own windows, do a
-\fBwnoutrefresh\fP on its windows, call \fBsetsyx\fP, and then call
-\fBdoupdate\fP.
-.PP
-Few applications will use this feature,
-most use \fBwmove\fP instead.
-.SS ripoffline
+.B \%getsyx
+and
+.B \%setsyx
+are designed to be used by a function that manipulates
+.I curses
+windows but seeks to avoid changing the cursor position.
+Such a function would first call
+.BR \%getsyx ","
+modify its windows' content,
+call \fB\%wnoutrefresh\fP(3X) on them,
+call
+.BR \%setsyx ","
+then call \fB\%doupdate\fP(3X).
+.PP
+Few applications use this feature;
+most call \fB\%wmove\fP(3X) instead.
+.SS curs_set
+The \fBcurs_set\fP routine sets the cursor state to invisible,
+normal, or very visible for \fBvisibility\fP equal to \fB0\fP,
+\fB1\fP, or \fB2\fP respectively.
+If the terminal supports the \fIvisibility\fP requested,
+the previous \fIcursor\fP state is returned;
+otherwise, \fBERR\fP is returned.
+.SS mvcur
+.B \%mvcur
+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 stream
+or are passed a function pointer to perform output,
+.B \%mvcur
+uses a file descriptor derived from the output stream parameter of
+\fB\%newterm\fP(3X).
.PP
-The \fBripoffline\fP routine provides access to the same facility that
-\fBslk_init\fP [see \fBcurs_slk\fP(3X)] uses to reduce the size of the
-screen.
-\fBripoffline\fP must be called before \fBinitscr\fP or
+One application of
+.B \%mvcur
+accompanies the temporary use of another program to write to the
+terminal screen.
+For example,
+first call \fB\%refresh\fP(3X) to ensure that the screen and the
+library's model of it is up to date;
+then call
+.BR \%reset_shell_mode ";"
+write to the screen with the external application;
+call
+.BR \%reset_prog_mode ";"
+and finally call
+.B \%mvcur
+to set the cursor's location to where
+.I \%curses
+thinks it is,
+since the library has no knowledge of how the external application
+moved it.
+.\" https://lists.gnu.org/archive/html/bug-ncurses/2016-10/msg00002.html
+.SS napms
+.B \%napms
+sleeps for
+.I ms
+milliseconds.
+If
+.I ms
+exceeds 30,000
+(thirty seconds),
+it is capped at that value.
+.SS ripoffline
+.B \%ripoffline
+provides access to the same facility that \fB\%slk_init\fP(3X) uses to
+reduce the size of the screen.
+\fB\%ripoffline\fP must be called before \fBinitscr\fP or
\fBnewterm\fP is called, to prepare these initial actions:
.bP
If \fIline\fP is positive, a line is removed from the top of \fBstdscr\fP.
.PP
\fBripoffline\fP can be called up to five times before calling \fBinitscr\fP or
\fBnewterm\fP.
-.SS curs_set
-.PP
-The \fBcurs_set\fP routine sets the cursor state to invisible,
-normal, or very visible for \fBvisibility\fP equal to \fB0\fP,
-\fB1\fP, or \fB2\fP respectively.
-If the terminal supports the \fIvisibility\fP requested,
-the previous \fIcursor\fP state is returned;
-otherwise, \fBERR\fP is returned.
-.SS napms
-.PP
-The \fBnapms\fP routine is used to sleep for \fIms\fP milliseconds.
.SH RETURN VALUE
Except for \fBcurs_set\fP, these routines always return \fBOK\fP.
.PP
X/Open defines no error conditions.
In this implementation
.TP 5
-.na
-.hy 0
\fBdef_prog_mode\fP, \fBdef_shell_mode\fP, \fBreset_prog_mode\fP, \fBreset_shell_mode\fP
-.hy
-.ad
-return an error
+return
+.B ERR
if the terminal was not initialized, or
if the I/O call to obtain the terminal settings fails.
.TP 5
\fBripoffline\fP
-returns an error if the maximum number of ripped-off lines
-exceeds the maximum (NRIPS = 5).
+returns
+.B ERR
+if the maximum number of ripped-off lines
+exceeds the maximum (5).
.SH NOTES
Note that \fBgetsyx\fP is a macro, so \fB&\fP is not necessary before
the variables \fIy\fP and \fIx\fP.
This implementation gets it right, but it may be unwise to count
on the correctness of the return value anywhere else.
.PP
-Both ncurses and SVr4 will call \fBcurs_set\fP in \fBendwin\fP
+Both \fI\%ncurses\fP and SVr4 will call \fBcurs_set\fP in \fBendwin\fP
if \fBcurs_set\fP
has been called to make the cursor other than normal, i.e., either
invisible or very visible.
-There is no way for ncurses to determine the initial cursor state to
-restore that.
+There is no way for \fI\%ncurses\fP to determine the initial cursor
+state to restore that.
+.SH EXTENSIONS
+In
+.IR \%ncurses ","
+.B \%mvcur
+accepts
+.B \-1
+for either or both old coordinates.
+This value 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 PORTABILITY
+Applications employing
+.I \%ncurses
+extensions should condition their use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
+.PP
The \fIvirtual screen\fP functions \fBsetsyx\fP and \fBgetsyx\fP
-are not described in the XSI Curses standard, Issue 4.
-All other functions are as described in XSI Curses.
+are not described in X/Open Curses, Issue 4.
+All other functions are as described in X/Open Curses.
.PP
The SVr4 documentation describes \fBsetsyx\fP and \fBgetsyx\fP
as having return type int.
This is misleading, as they are macros with no documented semantics
for the return value.
+.PP
+X/Open Curses notes:
+.RS
+.PP
+\*(``After use of
+.IR \%mvcur "(),"
+the model Curses maintains of the state of the terminal might not
+match the actual state of the terminal.
+An application should touch and refresh the window before
+resuming conventional use of Curses.\*(''
+.RE
+.PP
+Both
+.I \%ncurses
+and SVr4
+.I curses
+implement
+.B \%mvcur
+using the
+.I SCREEN
+data allocated in either \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X).
+X/Open Curses states that the old location must be given for
+.B \%mvcur
+to accommodate terminals that lack absolute cursor positioning.
+.\" X/Open Curses Issue 7, p. 161
+.PP
+If interrupted, \fI\%ncurses\fP restarts \fBnapms\fP.
+That, and the limitation to 30 seconds,
+are different from other implementations.
.SH SEE ALSO
-\fBcurses\fP(3X),
-\fBcurs_initscr\fP(3X),
-\fBcurs_outopts\fP(3X),
-\fBcurs_refresh\fP(3X),
-\fBcurs_scr_dump\fP(3X),
-\fBcurs_slk\fP(3X),
-\fBcurs_variables\fP(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_initscr\fP(3X),
+\fB\%curs_outopts\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_scr_dump\fP(3X),
+\fB\%curs_slk\fP(3X),
+\fB\%curs_variables\fP(3X)