jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: curs_kernel.3,v 1.10 2023/10/17 09:52:08 nicm Exp $
2.\"
3.\"***************************************************************************
4.\" Copyright 2018-2022,2023 Thomas E. Dickey *
5.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
6.\" *
7.\" Permission is hereby granted, free of charge, to any person obtaining a *
8.\" copy of this software and associated documentation files (the *
9.\" "Software"), to deal in the Software without restriction, including *
10.\" without limitation the rights to use, copy, modify, merge, publish, *
11.\" distribute, distribute with modifications, sublicense, and/or sell *
12.\" copies of the Software, and to permit persons to whom the Software is *
13.\" furnished to do so, subject to the following conditions: *
14.\" *
15.\" The above copyright notice and this permission notice shall be included *
16.\" in all copies or substantial portions of the Software. *
17.\" *
18.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
19.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
20.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
21.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
22.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
23.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
24.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
25.\" *
26.\" Except as contained in this notice, the name(s) of the above copyright *
27.\" holders shall not be used in advertising or otherwise to promote the *
28.\" sale, use or other dealings in this Software without prior written *
29.\" authorization. *
30.\"***************************************************************************
31.\"
32.\" $Id: curs_kernel.3,v 1.10 2023/10/17 09:52:08 nicm Exp $
33.ie \n(.g .ds `` \(lq
34.el .ds `` ``
35.ie \n(.g .ds '' \(rq
36.el .ds '' ''
37.de bP
38.ie n .IP \(bu 4
39.el .IP \(bu 2
40..
41.TH curs_kernel 3 2023-08-19 "ncurses 6.4" "Library calls"
42.na
43.hy 0
44.SH NAME
45\fBdef_prog_mode\fP,
46\fBdef_shell_mode\fP,
47\fBreset_prog_mode\fP,
48\fBreset_shell_mode\fP,
49\fBresetty\fP,
50\fBsavetty\fP,
51\fBgetsyx\fP,
52\fBsetsyx\fP,
53\fBripoffline\fP,
54\fBcurs_set\fP,
55\fBnapms\fP \- low-level \fBcurses\fP routines
56.ad
57.hy
58.SH SYNOPSIS
59\fB#include <curses.h>\fP
60.sp
61\fBint def_prog_mode(void);\fP
62.br
63\fBint def_shell_mode(void);\fP
64.sp
65\fBint reset_prog_mode(void);\fP
66.br
67\fBint reset_shell_mode(void);\fP
68.sp
69\fBint resetty(void);\fP
70.br
71\fBint savetty(void);\fP
72.sp
73\fBvoid getsyx(int \fIy\fB, int \fIx\fB);\fR
74.br
75\fBvoid setsyx(int \fIy\fB, int \fIx\fB);\fR
76.sp
77\fBint ripoffline(int \fIline\fB, int (*\fIinit\fB)(WINDOW *, int));\fR
78.br
79\fBint curs_set(int \fIvisibility\fB);\fR
80.br
81\fBint napms(int \fIms\fB);\fR
82.SH DESCRIPTION
83The following routines give low-level access
84to various \fBcurses\fP capabilities.
85These routines typically are used inside library routines.
86.SS def_prog_mode, def_shell_mode
87The \fBdef_prog_mode\fP and \fBdef_shell_mode\fP routines save the
88current terminal modes as the \*(``program\*(''
89(in \fBcurses\fP) or \*(``shell\*(''
90(not in \fBcurses\fP) state for use by the \fBreset_prog_mode\fP and
91\fBreset_shell_mode\fP routines.
92This is done automatically by \fBinitscr\fP.
93There is one such save area for each screen context
94allocated by \fBnewterm\fP.
95.SS reset_prog_mode, reset_shell_mode
96The \fBreset_prog_mode\fP and \fBreset_shell_mode\fP routines restore
97the terminal to \*(``program\*('' (in \fBcurses\fP) or \*(``shell\*('' (out of
98\fBcurses\fP) state.
99These are done automatically by \fBendwin\fP(3) and,
100after an \fBendwin\fP, by \fBdoupdate\fP,
101so they normally are not called.
102.SS resetty, savetty
103The \fBresetty\fP and \fBsavetty\fP routines save and restore the
104state of the terminal modes.
105\fBsavetty\fP saves the current state in
106a buffer and \fBresetty\fP restores the state to what it was at the
107last call to \fBsavetty\fP.
108.SS getsyx
109The \fBgetsyx\fP routine returns the current coordinates
110of the \fIvirtual screen\fP cursor in \fIy\fP and \fIx\fP.
111If \fBleaveok\fP is currently \fBTRUE\fP, then
112\fB\-1\fP,\fB\-1\fP is returned.
113If lines have been removed from the top of the
114screen, using \fBripoffline\fP, \fIy\fP and \fIx\fP include these lines;
115therefore, \fIy\fP and \fIx\fP should be used only as arguments for
116\fBsetsyx\fP.
117.PP
118Few applications will use this feature,
119most use \fBgetyx\fP instead.
120.SS setsyx
121The \fBsetsyx\fP routine sets
122the \fIvirtual screen\fP cursor to \fIy\fP, \fIx\fP.
123If \fIy\fP and \fIx\fP are both \fB\-1\fP, then
124\fBleaveok\fP is set.
125The two routines \fBgetsyx\fP and \fBsetsyx\fP
126are designed to be used by a library routine, which manipulates
127\fBcurses\fP windows but does not want to change the current position
128of the program's cursor.
129The library routine would call \fBgetsyx\fP
130at the beginning, do its manipulation of its own windows, do a
131\fBwnoutrefresh\fP on its windows, call \fBsetsyx\fP, and then call
132\fBdoupdate\fP.
133.PP
134Few applications will use this feature,
135most use \fBwmove\fP instead.
136.SS ripoffline
137The \fBripoffline\fP routine provides access to the same facility that
138\fBslk_init\fP [see \fBcurs_slk\fP(3)] uses to reduce the size of the
139screen.
140\fBripoffline\fP must be called before \fBinitscr\fP or
141\fBnewterm\fP is called, to prepare these initial actions:
142.bP
143If \fIline\fP is positive, a line is removed from the top of \fBstdscr\fP.
144.bP
145if \fIline\fP is negative, a line is removed from the bottom.
146.PP
147When the resulting initialization is done inside \fBinitscr\fP, the
148routine \fBinit\fP (supplied by the user) is called with two
149arguments:
150.bP
151a window pointer to the one-line window that has been
152allocated and
153.bP
154an integer with the number of columns in the window.
155.PP
156Inside this initialization routine, the integer variables \fBLINES\fP
157and \fBCOLS\fP (defined in \fB<curses.h>\fP) are not guaranteed to be
158accurate and \fBwrefresh\fP or \fBdoupdate\fP must not be called.
159It is allowable to call \fBwnoutrefresh\fP during the initialization routine.
160.PP
161\fBripoffline\fP can be called up to five times before calling \fBinitscr\fP or
162\fBnewterm\fP.
163.SS curs_set
164The \fBcurs_set\fP routine sets the cursor state to invisible,
165normal, or very visible for \fBvisibility\fP equal to \fB0\fP,
166\fB1\fP, or \fB2\fP respectively.
167If the terminal supports the \fIvisibility\fP requested,
168the previous \fIcursor\fP state is returned;
169otherwise, \fBERR\fP is returned.
170.SS napms
171The \fBnapms\fP routine is used to sleep for \fIms\fP milliseconds.
172.SH RETURN VALUE
173Except for \fBcurs_set\fP, these routines always return \fBOK\fP.
174.PP
175\fBcurs_set\fP
176returns the previous cursor state, or \fBERR\fP if the
177requested \fIvisibility\fP is not supported.
178.PP
179X/Open defines no error conditions.
180In this implementation
181.TP 5
182.na
183.hy 0
184\fBdef_prog_mode\fP, \fBdef_shell_mode\fP, \fBreset_prog_mode\fP, \fBreset_shell_mode\fP
185.hy
186.ad
187return an error
188if the terminal was not initialized, or
189if the I/O call to obtain the terminal settings fails.
190.TP 5
191\fBripoffline\fP
192returns an error if the maximum number of ripped-off lines
193exceeds the maximum (NRIPS = 5).
194.SH NOTES
195Note that \fBgetsyx\fP is a macro, so \fB&\fP is not necessary before
196the variables \fIy\fP and \fIx\fP.
197.PP
198Older SVr4 man pages warn that the return value
199of \fBcurs_set\fP \*(``is currently incorrect\*(''.
200This implementation gets it right, but it may be unwise to count
201on the correctness of the return value anywhere else.
202.PP
203Both ncurses and SVr4 will call \fBcurs_set\fP in \fBendwin\fP
204if \fBcurs_set\fP
205has been called to make the cursor other than normal, i.e., either
206invisible or very visible.
207There is no way for ncurses to determine the initial cursor state to
208restore that.
209.SH PORTABILITY
210The \fIvirtual screen\fP functions \fBsetsyx\fP and \fBgetsyx\fP
211are not described in the XSI Curses standard, Issue 4.
212All other functions are as described in XSI Curses.
213.PP
214The SVr4 documentation describes \fBsetsyx\fP and \fBgetsyx\fP
215as having return type int.
216This is misleading, as they are macros with no documented semantics
217for the return value.
218.SH SEE ALSO
219\fBcurses\fP(3),
220\fBcurs_initscr\fP(3),
221\fBcurs_outopts\fP(3),
222\fBcurs_refresh\fP(3),
223\fBcurs_scr_dump\fP(3),
224\fBcurs_slk\fP(3),
225\fBcurs_variables\fP(3).