diff options
Diffstat (limited to 'man/curs_kernel.3x')
| -rw-r--r-- | man/curs_kernel.3x | 278 |
1 files changed, 139 insertions, 139 deletions
diff --git a/man/curs_kernel.3x b/man/curs_kernel.3x index a4e6c808b08e..e85c132768a3 100644 --- a/man/curs_kernel.3x +++ b/man/curs_kernel.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2019,2020 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 * @@ -27,129 +27,123 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_kernel.3x,v 1.29 2020/10/17 23:22:35 tom Exp $ -.ie \n(.g .ds `` \(lq -.el .ds `` `` -.ie \n(.g .ds '' \(rq -.el .ds '' '' +.\" $Id: curs_kernel.3x,v 1.61 2024/04/20 21:24:19 tom Exp $ +.TH curs_kernel 3X 2024-04-20 "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 "" -.na -.hy 0 .SH NAME -\fBdef_prog_mode\fR, -\fBdef_shell_mode\fR, -\fBreset_prog_mode\fR, -\fBreset_shell_mode\fR, -\fBresetty\fR, -\fBsavetty\fR, -\fBgetsyx\fR, -\fBsetsyx\fR, -\fBripoffline\fR, -\fBcurs_set\fR, -\fBnapms\fR \- low-level \fBcurses\fR 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\%ripoffline\fP, +\fB\%curs_set\fP, +\fB\%napms\fP \- +low-level \fIcurses\fR routines .SH SYNOPSIS -\fB#include <curses.h>\fR -.sp -\fBint def_prog_mode(void);\fR -.br -\fBint def_shell_mode(void);\fR -.sp -\fBint reset_prog_mode(void);\fR -.br -\fBint reset_shell_mode(void);\fR -.sp -\fBint resetty(void);\fR -.br -\fBint savetty(void);\fR -.sp -\fBvoid getsyx(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR -.br -\fBvoid setsyx(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR -.sp -\fBint ripoffline(int \fP\fIline\fP\fB, int (*\fP\fIinit\fP\fB)(WINDOW *, int));\fR -.br -\fBint curs_set(int \fP\fIvisibility\fP\fB);\fR -.br -\fBint napms(int \fP\fIms\fP\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 ripoffline(int \fIline\fP, int (*\fIinit\fP)(WINDOW *, int)); +\fBint curs_set(int \fIvisibility\fP); +\fBint napms(int \fIms\fP); +.fi .SH DESCRIPTION The following routines give low-level access -to various \fBcurses\fR capabilities. +to various \fBcurses\fP capabilities. These routines typically are used inside library routines. -.SS def_prog_mode, def_shell_mode -.PP -The \fBdef_prog_mode\fR and \fBdef_shell_mode\fR routines save the -current terminal modes as the \*(``program\*('' (in \fBcurses\fR) or \*(``shell\*('' -(not in \fBcurses\fR) state for use by the \fBreset_prog_mode\fR and -\fBreset_shell_mode\fR routines. -This is done automatically by \fBinitscr\fR. +.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\*('' +(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\fR. -.SS reset_prog_mode, reset_shell_mode -.PP -The \fBreset_prog_mode\fR and \fBreset_shell_mode\fR routines restore -the terminal to \*(``program\*('' (in \fBcurses\fR) or \*(``shell\*('' (out of -\fBcurses\fR) state. -These are done automatically by \fBendwin\fR(3X) and, -after an \fBendwin\fR, by \fBdoupdate\fR, +allocated by \fBnewterm\fP. +.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 -The \fBresetty\fR and \fBsavetty\fR routines save and restore the +.SS "resetty, savetty" +The \fBresetty\fP and \fBsavetty\fP routines save and restore the state of the terminal modes. -\fBsavetty\fR saves the current state in -a buffer and \fBresetty\fR restores the state to what it was at the -last call to \fBsavetty\fR. +\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 -.PP -The \fBgetsyx\fR routine returns the current coordinates -of the \fIvirtual screen\fP cursor in \fIy\fR and \fIx\fR. -If \fBleaveok\fR is currently \fBTRUE\fR, then -\fB\-1\fR,\fB\-1\fR is returned. +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\fR, \fIy\fR and \fIx\fR include these lines; -therefore, \fIy\fR and \fIx\fR should be used only as arguments for -\fBsetsyx\fR. +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. .SS setsyx -.PP -The \fBsetsyx\fR routine sets -the \fIvirtual screen\fP cursor to \fIy\fR, \fIx\fR. -If \fIy\fR and \fIx\fR are both \fB\-1\fR, then -\fBleaveok\fR is set. -The two routines \fBgetsyx\fR and \fBsetsyx\fR +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\fR windows but does not want to change the current position +\fBcurses\fP windows but does not want to change the current position of the program's cursor. -The library routine would call \fBgetsyx\fR +The library routine would call \fBgetsyx\fP at the beginning, do its manipulation of its own windows, do a -\fBwnoutrefresh\fR on its windows, call \fBsetsyx\fR, and then call -\fBdoupdate\fR. +\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 -.PP -The \fBripoffline\fR routine provides access to the same facility that -\fBslk_init\fR [see \fBcurs_slk\fR(3X)] uses to reduce the size of the -screen. -\fBripoffline\fR must be called before \fBinitscr\fR or -\fBnewterm\fR is called, to prepare these initial actions: +.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\fR is positive, a line is removed from the top of \fBstdscr\fR. +If \fIline\fP is positive, a line is removed from the top of \fBstdscr\fP. .bP -if \fIline\fR is negative, a line is removed from the bottom. +if \fIline\fP is negative, a line is removed from the bottom. .PP -When the resulting initialization is done inside \fBinitscr\fR, the -routine \fBinit\fR (supplied by the user) is called with two +When the resulting initialization is done inside \fBinitscr\fP, the +routine \fBinit\fP (supplied by the user) is called with two arguments: .bP a window pointer to the one-line window that has been @@ -157,75 +151,81 @@ allocated and .bP an integer with the number of columns in the window. .PP -Inside this initialization routine, the integer variables \fBLINES\fR -and \fBCOLS\fR (defined in \fB<curses.h>\fR) are not guaranteed to be -accurate and \fBwrefresh\fR or \fBdoupdate\fR must not be called. -It is allowable to call \fBwnoutrefresh\fR during the initialization routine. +Inside this initialization routine, the integer variables \fBLINES\fP +and \fBCOLS\fP (defined in \fB<curses.h>\fP) are not guaranteed to be +accurate and \fBwrefresh\fP or \fBdoupdate\fP must not be called. +It is allowable to call \fBwnoutrefresh\fP during the initialization routine. .PP -\fBripoffline\fR can be called up to five times before calling \fBinitscr\fR or -\fBnewterm\fR. +\fBripoffline\fP can be called up to five times before calling \fBinitscr\fP or +\fBnewterm\fP. .SS curs_set -.PP -The \fBcurs_set\fR routine sets the cursor state to invisible, -normal, or very visible for \fBvisibility\fR equal to \fB0\fR, -\fB1\fR, or \fB2\fR respectively. -If the terminal supports the \fIvisibility\fR requested, -the previous \fIcursor\fR state is returned; -otherwise, \fBERR\fR is returned. +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\fR routine is used to sleep for \fIms\fR milliseconds. +.B \%napms +sleeps for +.I ms +milliseconds. +If +.I ms +exceeds 30,000 +(thirty seconds), +it is capped at that value. .SH RETURN VALUE -Except for \fBcurs_set\fR, these routines always return \fBOK\fR. +Except for \fBcurs_set\fP, these routines always return \fBOK\fP. .PP -\fBcurs_set\fR -returns the previous cursor state, or \fBERR\fR if the -requested \fIvisibility\fR is not supported. +\fBcurs_set\fP +returns the previous cursor state, or \fBERR\fP if the +requested \fIvisibility\fP is not supported. .PP X/Open defines no error conditions. In this implementation .TP 5 -.na -.hy 0 -\fBdef_prog_mode\fR, \fBdef_shell_mode\fR, \fBreset_prog_mode\fR, \fBreset_shell_mode\fR -.hy -.ad +\fBdef_prog_mode\fP, \fBdef_shell_mode\fP, \fBreset_prog_mode\fP, \fBreset_shell_mode\fP return an error 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). +exceeds the maximum (5). .SH NOTES -Note that \fBgetsyx\fR is a macro, so \fB&\fR is not necessary before -the variables \fIy\fR and \fIx\fR. +Note that \fBgetsyx\fP is a macro, so \fB&\fP is not necessary before +the variables \fIy\fP and \fIx\fP. .PP Older SVr4 man pages warn that the return value -of \fBcurs_set\fR \*(``is currently incorrect\*(''. +of \fBcurs_set\fP \*(``is currently incorrect\*(''. 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\fR in \fBendwin\fR -if \fBcurs_set\fR +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 PORTABILITY -The \fIvirtual screen\fP functions \fBsetsyx\fR and \fBgetsyx\fR -are not described in the XSI Curses standard, Issue 4. -All other functions are as described in XSI Curses. +The \fIvirtual screen\fP functions \fBsetsyx\fP and \fBgetsyx\fP +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\fR and \fBgetsyx\fR +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 +If interrupted, \fI\%ncurses\fP restarts \fBnapms\fP. +That, and the limitation to 30 seconds, +are different from other implementations. .SH SEE ALSO -\fBcurses\fR(3X), -\fBcurs_initscr\fR(3X), -\fBcurs_outopts\fR(3X), -\fBcurs_refresh\fR(3X), -\fBcurs_scr_dump\fR(3X), -\fBcurs_slk\fR(3X), -\fBcurs_variables\fR(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) |