Debian Codegraph @

upstream/debian-trixie/man3/kernel.3ncurses

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-2024,2025 Thomas E. Dickey *
3 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
4 .\" *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a *
6 .\" copy of this software and associated documentation files (the *
7 .\" "Software"), to deal in the Software without restriction, including *
8 .\" without limitation the rights to use, copy, modify, merge, publish, *
9 .\" distribute, distribute with modifications, sublicense, and/or sell *
10 .\" copies of the Software, and to permit persons to whom the Software is *
11 .\" furnished to do so, subject to the following conditions: *
12 .\" *
13 .\" The above copyright notice and this permission notice shall be included *
14 .\" in all copies or substantial portions of the Software. *
15 .\" *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
23 .\" *
24 .\" Except as contained in this notice, the name(s) of the above copyright *
25 .\" holders shall not be used in advertising or otherwise to promote the *
26 .\" sale, use or other dealings in this Software without prior written *
27 .\" authorization. *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: curs_kernel.3x,v 1.77 2025/02/15 15:13:55 tom Exp $
31 .TH kernel 3NCURSES 2025-02-15 "ncurses 6.5" "Library calls"
32 .ie \n(.g \{\
33 .ds `` \(lq
34 .ds '' \(rq
35 .\}
36 .el \{\
37 .ie t .ds `` ``
38 .el .ds `` ""
39 .ie t .ds '' ''
40 .el .ds '' ""
41 .\}
42 .
43 .de bP
44 .ie n .IP \(bu 4
45 .el .IP \(bu 2
46 ..
47 .SH NAME
48 \fB\%def_prog_mode\fP,
49 \fB\%def_shell_mode\fP,
50 \fB\%reset_prog_mode\fP,
51 \fB\%reset_shell_mode\fP,
52 \fB\%resetty\fP,
53 \fB\%savetty\fP,
54 \fB\%getsyx\fP,
55 \fB\%setsyx\fP,
56 \fB\%curs_set\fP,
57 \fB\%mvcur\fP,
58 \fB\%napms\fP,
59 \fB\%ripoffline\fP \-
60 low-level \fIcurses\fR routines
61 .SH SYNOPSIS
62 .nf
63 \fB#include <curses.h>
64 .PP
65 \fBint def_prog_mode(void);
66 \fBint def_shell_mode(void);
67 .PP
68 \fBint reset_prog_mode(void);
69 \fBint reset_shell_mode(void);
70 .PP
71 \fBint resetty(void);
72 \fBint savetty(void);
73 .PP
74 \fBvoid getsyx(int \fIy\fP, int \fIx\fP);
75 \fBvoid setsyx(int \fIy\fP, int \fIx\fP);
76 .PP
77 \fBint curs_set(int \fIvisibility\fP);
78 \fBint mvcur(int \fIoldrow\fP, int \fIoldcol\fP, int \fInewrow\fP, int \fInewcol\fP);
79 \fBint napms(int \fIms\fP);
80 \fBint ripoffline(int \fIline\fP, int (*\fIinit\fP)(WINDOW *, int));
81 .fi
82 .SH DESCRIPTION
83 The following routines give low-level access
84 to various \fBcurses\fP capabilities.
85 These routines typically are used inside library routines.
86 .SS "def_prog_mode, def_shell_mode"
87 The \fBdef_prog_mode\fP and \fBdef_shell_mode\fP routines save the
88 current 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.
92 This is done automatically by \fBinitscr\fP.
93 There is one such save area for each screen context
94 allocated by \fBnewterm\fP.
95 .SS "reset_prog_mode, reset_shell_mode"
96 The \fBreset_prog_mode\fP and \fBreset_shell_mode\fP routines restore
97 the terminal to \*(``program\*('' (in \fBcurses\fP) or \*(``shell\*('' (out of
98 \fBcurses\fP) state.
99 These are done automatically by \fB\%endwin\fP(3NCURSES) and,
100 after an \fBendwin\fP, by \fBdoupdate\fP,
101 so they normally are not called.
102 .SS "resetty, savetty"
103 The \fBresetty\fP and \fBsavetty\fP routines save and restore the
104 state of the terminal modes.
105 \fBsavetty\fP saves the current state in
106 a buffer and \fBresetty\fP restores the state to what it was at the
107 last call to \fBsavetty\fP.
108 .SS getsyx
109 .B \%getsyx
110 stores the coordinates of virtual screen
111 .RB \%( newscr )
112 cursor in
113 .I y
114 and
115 .IR x "."
116 If
117 .BR \%newscr 's
118 \fB\%leaveok\fP(3NCURSES) output option is
119 .BR TRUE ","
120 .B \%getsyx
121 stores
122 .B \-1
123 in both
124 .I y
125 and
126 .IR x "."
127 If lines have been removed from the top of the screen using
128 .BR \%ripoffline ","
129 .I y
130 includes these lines;
131 therefore,
132 .I y
133 and
134 .I x
135 populated by
136 .B \%getsyx
137 should be used only as arguments for
138 .BR \%setsyx "."
139 .PP
140 Few applications use this feature;
141 most call \fB\%getyx\fP(3NCURSES) instead.
142 .SS setsyx
143 .B \%setsyx
144 sets the virtual screen
145 .RB \%( newscr )
146 cursor location to
147 .RI ( y ,
148 .IR x ")."
149 .B "\%setsyx(\-1, \-1)"
150 is equivalent to
151 .BR "\%leaveok(newscr, TRUE)" "."
152 .PP
153 .B \%getsyx
154 and
155 .B \%setsyx
156 are designed to be used by a function that manipulates
157 .I curses
158 windows but seeks to avoid changing the cursor position.
159 Such a function would first call
160 .BR \%getsyx ","
161 modify its windows' content,
162 call \fB\%wnoutrefresh\fP(3NCURSES) on them,
163 call
164 .BR \%setsyx ","
165 then call \fB\%doupdate\fP(3NCURSES).
166 .PP
167 Few applications use this feature;
168 most call \fB\%wmove\fP(3NCURSES) instead.
169 .SS curs_set
170 .B \%curs_set
171 adjusts the cursor visibility to
172 \*(``invisible\*('',
173 \*(``visible\*('',
174 \*(``very visible\*('',
175 as its argument is
176 .BR 0 ,
177 .BR 1 ,
178 or
179 .BR 2 ,
180 respectively.
181 It returns the previous
182 .I visibility
183 if the requested one is supported,
184 and
185 .B ERR
186 otherwise.
187 .SS mvcur
188 .B \%mvcur
189 provides low-level cursor motion.
190 It takes effect immediately,
191 rather than at the next refresh.
192 Unlike the other low-level output functions,
193 which either write to the standard output stream
194 or are passed a function pointer to perform output,
195 .B \%mvcur
196 uses a file descriptor derived from the output stream parameter of
197 \fB\%newterm\fP(3NCURSES).
198 .PP
199 One application of
200 .B \%mvcur
201 accompanies the temporary use of another program to write to the
202 terminal screen.
203 For example,
204 first call \fB\%refresh\fP(3NCURSES) to ensure that the screen and the
205 library's model of it is up to date;
206 then call
207 .BR \%reset_shell_mode ";"
208 write to the screen with the external application;
209 call
210 .BR \%reset_prog_mode ";"
211 and finally call
212 .BR \%mvcur( ".\|.\|." ,
213 .RB .\|.\|. ,
214 .B \-1, \-1)
215 to move the terminal cursor to where
216 .I \%curses
217 thinks it is,
218 since the library has no knowledge of how the external application
219 moved it.
220 .\" https://lists.gnu.org/archive/html/bug-ncurses/2016-10/msg00002.html
221 .SS napms
222 .B \%napms
223 sleeps for
224 .I ms
225 milliseconds.
226 If
227 .I ms
228 exceeds 30,000
229 (thirty seconds),
230 it is capped at that value.
231 .SS ripoffline
232 .B \%ripoffline
233 provides access to the same facility that \fB\%slk_init\fP(3NCURSES) uses to
234 reduce the size of the screen.
235 \fB\%ripoffline\fP must be called before \fBinitscr\fP or
236 \fBnewterm\fP is called, to prepare these initial actions:
237 .bP
238 If \fIline\fP is positive, a line is removed from the top of \fBstdscr\fP.
239 .bP
240 if \fIline\fP is negative, a line is removed from the bottom.
241 .PP
242 When the resulting initialization is done inside \fBinitscr\fP, the
243 routine \fBinit\fP (supplied by the user) is called with two
244 arguments:
245 .bP
246 a window pointer to the one-line window that has been
247 allocated and
248 .bP
249 an integer with the number of columns in the window.
250 .PP
251 Inside this initialization routine, the integer variables \fBLINES\fP
252 and \fBCOLS\fP (defined in \fB<curses.h>\fP) are not guaranteed to be
253 accurate and \fBwrefresh\fP or \fBdoupdate\fP must not be called.
254 It is allowable to call \fBwnoutrefresh\fP during the initialization routine.
255 .PP
256 \fBripoffline\fP can be called up to five times before calling \fBinitscr\fP or
257 \fBnewterm\fP.
258 .SH RETURN VALUE
259 Except for
260 .BR \%curs_set ","
261 these functions return
262 .B OK
263 on success and
264 .B ERR
265 on failure.
266 .PP
267 .B \%curs_set
268 returns the previous cursor visibility,
269 and returns
270 .B ERR
271 if the terminal type does not support the requested
272 .IR visibility "."
273 .PP
274 .B \%napms
275 always succeeds.
276 .PP
277 .B \%mvcur
278 fails if the position
279 .RI ( newrow ,
280 .IR newcol )
281 is outside the screen boundaries.
282 .PP
283 In
284 .IR \%ncurses ","
285 .bP
286 .BR \%def_prog_mode ","
287 .BR \%def_shell_mode ","
288 .BR \%reset_prog_mode ","
289 and
290 .B \%reset_shell_mode
291 return
292 .B ERR
293 if the terminal was not initialized,
294 or if the operating system's function for obtaining terminal settings
295 fails.
296 .bP
297 .B \%ripoffline
298 returns
299 .B ERR
300 if the accumulated quantity of ripped-off lines
301 would exceed the maximum (5).
302 .SH NOTES
303 .B \%getsyx
304 is a macro;
305 use of the
306 .B &
307 operator before its arguments is unnecessary.
308 .PP
309 The
310 .B \%endwin
311 function of both
312 .I \%ncurses
313 and SVr4
314 .I curses
315 calls
316 .B \%curs_set
317 if the latter has previously been called to set the cursor visibility
318 to a value other than normal;
319 that is,
320 either
321 invisible or very visible.
322 There is no way for
323 .I \%ncurses
324 to determine the initial cursor visibility to restore it.
325 .SH EXTENSIONS
326 In
327 .IR \%ncurses ","
328 .B \%mvcur
329 accepts
330 .B \-1
331 for either or both old coordinates.
332 This value tells
333 .I \%ncurses
334 that the old location is unknown,
335 and that it must use only absolute motion,
336 as with the
337 .B \%cursor_address
338 .RB ( cup )
339 capability,
340 rather than the least costly combination of absolute and relative
341 motion.
342 .SH PORTABILITY
343 Applications employing
344 .I \%ncurses
345 extensions should condition their use on the visibility of the
346 .B \%NCURSES_VERSION
347 preprocessor macro.
348 .PP
349 The
350 .I "virtual screen"
351 functions
352 .I \%setsyx
353 and
354 .I \%getsyx
355 are not described in X/Open Curses Issue\ 4.
356 SVr4 documents each of them
357 as returning an
358 .IR int "."
359 This is misleading,
360 as they are macros with no documented semantics for returning values.
361 .PP
362 All other functions are as described in X/Open Curses.
363 It specifies no error conditions for them,
364 except as described for
365 .I \%curs_set
366 in section \*(``RETURN VALUE\*('' above.
367 .PP
368 The System\ V Interface Definition,
369 Version 4 (1995),
370 specified all of these functions except
371 .I \%curs_set
372 as returning
373 .IR OK "."
374 .\" SVID 4, vol 3., p. 518
375 .PP
376 Older SVr4 man pages warn that the return value of
377 .B \%curs_set
378 \*(``is currently incorrect\*(''.
379 This implementation gets it right,
380 but counting on its correctness anywhere else may be unwise.
381 .PP
382 X/Open Curses specifies
383 .I \%ripoffline
384 as returning
385 .B OK
386 with no possibility of failure
387 (\*(``[c]alls to
388 .I \%ripoffline
389 above this limit
390 [five lines]
391 have no effect but report success\*('').
392 .PP
393 X/Open Curses notes:
394 .RS
395 .PP
396 After use of
397 .IR \%mvcur "(),"
398 the model Curses maintains of the state of the terminal might not
399 match the actual state of the terminal.
400 An application should touch and refresh the window before
401 resuming conventional use of Curses.
402 .RE
403 .PP
404 Both
405 .I \%ncurses
406 and SVr4
407 .I curses
408 implement
409 .B \%mvcur
410 using the
411 .I SCREEN
412 object allocated in either \fB\%initscr\fP(3NCURSES) or \fB\%newterm\fP(3NCURSES).
413 X/Open Curses states that the old location must be given for
414 .I \%mvcur
415 to accommodate terminals that lack absolute cursor positioning.
416 .\" X/Open Curses Issue 7, p. 161
417 .PP
418 If interrupted by a signal,
419 .I \%ncurses
420 restarts
421 .IR \%napms "."
422 That,
423 and the limitation to 30 seconds,
424 differ from other implementations.
425 .SH SEE ALSO
426 \fB\%ncurses\fP(3NCURSES),
427 \fB\%initscr\fP(3NCURSES),
428 \fB\%outopts\fP(3NCURSES),
429 \fB\%refresh\fP(3NCURSES),
430 \fB\%scr_dump\fP(3NCURSES),
431 \fB\%slk\fP(3NCURSES),
432 \fB\%curses_variables\fP(3NCURSES)