Debian Codegraph @

upstream/debian-unstable/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.89 2025/08/16 19:50:07 tom Exp $
31 .TH kernel 3NCURSES 2025-08-16 "ncurses 6.6" "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 \fBendwin\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 are 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 .I \%ncurses
231 caps it at that value.
232 .SS ripoffline
233 .B \%ripoffline
234 provides access to the same facility that \fB\%slk_init\fP(3NCURSES) uses to
235 reduce the size of the screen.
236 The application must call
237 .B \%ripoffline
238 before \fB\%initscr\fP(3NCURSES) or \fB\%newterm\fP(3NCURSES)
239 so that the latter functions prepare a
240 .B \%stdscr
241 of the correct size.
242 .bP
243 If
244 .I line
245 is positive,
246 .B \%ripoffline
247 removes a line from the top of what will become
248 .BR \%stdscr "."
249 .bP
250 If
251 .I line
252 is negative,
253 .B \%ripoffline
254 removes a line from the bottom of what will become
255 .BR \%stdscr "."
256 .PP
257 When
258 .B \%initscr
259 initializes
260 .IR curses ","
261 it calls the
262 .I init
263 function supplied to
264 .B \%ripoffline
265 by the application with two arguments:
266 .bP
267 a pointer to the one-line
268 .I \%WINDOW
269 that it allocates,
270 and
271 .bP
272 an integer with the number of columns in the window.
273 .PP
274 Inside this
275 .I init
276 function,
277 the values of the integer variables
278 .B LINES
279 and
280 .B COLS
281 (see \fB\%curses_variables\fP(3NCURSES))
282 are not guaranteed to be reliable;
283 it must not call \fB\%wrefresh\fP(3NCURSES) or \fB\%doupdate\fP(3NCURSES).
284 A \fB\%wnoutrefresh\fP(3NCURSES) call is permissible.
285 .PP
286 .B \%ripoffline
287 can be called up to five times before
288 .B \%initscr
289 or
290 .BR \%newterm "."
291 .SH RETURN VALUE
292 Except for
293 .BR \%curs_set ","
294 these functions return
295 .B OK
296 on success and
297 .B ERR
298 on failure.
299 .PP
300 .B \%curs_set
301 returns the previous cursor visibility,
302 and returns
303 .B ERR
304 if the terminal type does not support the requested
305 .IR visibility "."
306 .PP
307 .B \%napms
308 always succeeds.
309 .PP
310 .B \%mvcur
311 fails if the position
312 .RI ( newrow ,
313 .IR newcol )
314 is outside the screen boundaries.
315 .PP
316 In
317 .IR \%ncurses ","
318 .bP
319 .BR \%def_prog_mode ","
320 .BR \%def_shell_mode ","
321 .BR \%reset_prog_mode ","
322 and
323 .B \%reset_shell_mode
324 return
325 .B ERR
326 if the terminal was not initialized,
327 or if the operating system's function for obtaining terminal settings
328 fails.
329 .bP
330 .B \%ripoffline
331 returns
332 .B ERR
333 if the accumulated quantity of ripped-off lines
334 would exceed the maximum (5).
335 .SH NOTES
336 .B \%getsyx
337 is a macro;
338 use of the
339 .B &
340 operator before its arguments is unnecessary.
341 .PP
342 The
343 .B \%endwin
344 function of both
345 .I \%ncurses
346 and SVr4
347 .I curses
348 calls
349 .B \%curs_set
350 if the latter has previously been called to set the cursor visibility
351 to a value other than normal;
352 that is,
353 either
354 invisible or very visible.
355 There is no way for
356 .I \%ncurses
357 to determine the initial cursor visibility to restore it.
358 .PP
359 .I \%ncurses
360 imposes a limit of 30 seconds on a delay requested of
361 .BR \%napms .
362 .PP
363 While the
364 .I init
365 function called by
366 .B \%ripoffline
367 is specified to return an
368 .IR int ","
369 .I \%ncurses
370 pays no attention to its return value.
371 .PP
372 If
373 .B \%ripoffline
374 cannot allocate memory for the required
375 .I \%WINDOW
376 structure backing the ripped-off line,
377 it stores a null pointer to the
378 .I \%WINDOW
379 pointer argument supplied by the
380 .I init
381 function the application specifies.
382 The application must check this argument for validity after calling
383 .B \%initscr
384 and prior to performing
385 .I curses
386 operations on that window.
387 .SH EXTENSIONS
388 In
389 .IR \%ncurses ","
390 .B \%mvcur
391 accepts
392 .B \-1
393 for either or both old coordinates.
394 This value tells
395 .I \%ncurses
396 that the old location is unknown,
397 and that it must use only absolute motion,
398 as with the
399 .B \%cursor_address
400 .RB ( cup )
401 capability,
402 rather than the least costly combination of absolute and relative
403 motion.
404 .SH PORTABILITY
405 Applications employing
406 .I \%ncurses
407 extensions should condition their use on the visibility of the
408 .B \%NCURSES_VERSION
409 preprocessor macro.
410 .PP
411 The
412 .I "virtual screen"
413 functions
414 .I \%setsyx
415 and
416 .I \%getsyx
417 are not described in X/Open Curses Issue\ 4.
418 SVr4 documents each of them
419 as returning an
420 .IR int "."
421 This is misleading,
422 as they are macros with no documented semantics for returning values.
423 .PP
424 All other functions are as described in X/Open Curses.
425 It specifies no error conditions for them,
426 except as described for
427 .I \%curs_set
428 in section \*(``RETURN VALUE\*('' above.
429 .PP
430 The System\ V Interface Definition,
431 Version 4 (1995),
432 specified all of these functions except
433 .I \%curs_set
434 as returning
435 .IR OK "."
436 .\" SVID 4, vol 3., p. 518
437 .PP
438 Older SVr4 man pages warn that the return value of
439 .I \%curs_set
440 \*(``is currently incorrect\*(''.
441 This implementation gets it right,
442 but counting on its correctness anywhere else may be unwise.
443 .PP
444 X/Open Curses specifies
445 .I \%ripoffline
446 as returning
447 .I OK
448 with no possibility of failure
449 (\*(``[c]alls to
450 .I \%ripoffline
451 above this limit
452 [five lines]
453 have no effect but report success\*('').
454 .PP
455 X/Open Curses notes:
456 .RS
457 .PP
458 After use of
459 .IR \%mvcur "(),"
460 the model Curses maintains of the state of the terminal might not
461 match the actual state of the terminal.
462 An application should touch and refresh the window before
463 resuming conventional use of Curses.
464 .RE
465 .PP
466 Both
467 .I \%ncurses
468 and SVr4
469 .I curses
470 implement
471 .I \%mvcur
472 using the
473 .I SCREEN
474 object allocated in either \fB\%initscr\fP(3NCURSES) or \fB\%newterm\fP(3NCURSES).
475 X/Open Curses states that the old location must be given for
476 .I \%mvcur
477 to accommodate terminals that lack absolute cursor positioning.
478 .\" X/Open Curses Issue 7, p. 161
479 .PP
480 If interrupted by a signal,
481 .I \%ncurses
482 restarts
483 .IR \%napms "."
484 That,
485 and the limitation to 30 seconds,
486 differ from other implementations.
487 .SH SEE ALSO
488 \fB\%ncurses\fP(3NCURSES),
489 \fB\%initscr\fP(3NCURSES),
490 \fB\%outopts\fP(3NCURSES),
491 \fB\%refresh\fP(3NCURSES),
492 \fB\%scr_dump\fP(3NCURSES),
493 \fB\%slk\fP(3NCURSES),
494 \fB\%curses_variables\fP(3NCURSES)