Debian Codegraph @

upstream/mageia-cauldron/man3/curs_kernel.3x

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