ncurses 6.3 - patch 20211120

[ncurses.git] / man / ncurses.3x

diff --git a/man/ncurses.3x b/man/ncurses.3x
index 33cc04a710936656181f07725173fdbb184b8160..fb1279419654edcd8ab13c9df97bf5eed5cfbb52 100644 (file)
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -1,6 +1,6 @@
 '\" t
 .\"***************************************************************************
 '\" t
 .\"***************************************************************************

-.\" Copyright 2018-2019,2020 Thomas E. Dickey                                *
+.\" Copyright 2018-2020,2021 Thomas E. Dickey                                *

 .\" Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *


@@ -28,7 +28,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: ncurses.3x,v 1.147 2020/03/21 23:38:25 tom Exp $
+.\" $Id: ncurses.3x,v 1.153 2021/08/22 17:17:16 tom Exp $

 .hy 0
 .TH ncurses 3X ""
 .ie \n(.g .ds `` \(lq
 .hy 0
 .TH ncurses 3X ""
 .ie \n(.g .ds `` \(lq


@@ -89,7 +89,7 @@ A program using these routines must be linked with the \fB\-lncurses\fR option,
 or (if it has been generated) with the debugging library \fB\-lncurses_g\fR.
 (Your system integrator may also have installed these libraries under
 the names \fB\-lcurses\fR and \fB\-lcurses_g\fR.)
 or (if it has been generated) with the debugging library \fB\-lncurses_g\fR.
 (Your system integrator may also have installed these libraries under
 the names \fB\-lcurses\fR and \fB\-lcurses_g\fR.)

-The ncurses_g library generates trace logs (in a file called 'trace' in the
+The ncurses_g library generates trace logs (in a file called \*(``trace\*('' in the

 current directory) that describe curses actions.
 See also the section on \fBALTERNATE CONFIGURATIONS\fP.
 .PP
 current directory) that describe curses actions.
 See also the section on \fBALTERNATE CONFIGURATIONS\fP.
 .PP


@@ -127,7 +127,6 @@ sequence should be used:
 .PP
 Most programs would additionally use the sequence:
 .NS
 .PP
 Most programs would additionally use the sequence:
 .NS

-\fBnonl();\fR

 \fBintrflush(stdscr, FALSE);\fR
 \fBkeypad(stdscr, TRUE);\fR
 .NE
 \fBintrflush(stdscr, FALSE);\fR
 \fBkeypad(stdscr, TRUE);\fR
 .NE


@@ -319,8 +318,9 @@ For example, \fBwaddch\fP becomes \fBwadd_wch\fP.
 .PP
 .\"
 .SS Routine Name Index
 .PP
 .\"
 .SS Routine Name Index

-The following table lists each \fBcurses\fR routine and the name of
-the manual page on which it is described.
+The following table lists the \fBcurses\fR routines provided in
+the \*(``normal\*('' and \*(``wide\*('' libraries and the names of
+the manual pages on which they are described.

 Routines flagged with \*(``*\*(''
 are ncurses-specific, not described by XPG4 or present in SVr4.
 .PP
 Routines flagged with \*(``*\*(''
 are ncurses-specific, not described by XPG4 or present in SVr4.
 .PP


@@ -332,17 +332,6 @@ l l .
 =
 COLOR_PAIR/\fBcurs_color\fR(3X)
 PAIR_NUMBER/\fBcurs_attr\fR(3X)
 =
 COLOR_PAIR/\fBcurs_color\fR(3X)
 PAIR_NUMBER/\fBcurs_attr\fR(3X)

-_nc_free_and_exit/\fBcurs_memleaks\fR(3X)*
-_nc_freeall/\fBcurs_memleaks\fR(3X)*
-_nc_tracebits/\fBcurs_trace\fR(3X)*
-_traceattr/\fBcurs_trace\fR(3X)*
-_traceattr2/\fBcurs_trace\fR(3X)*
-_tracechar/\fBcurs_trace\fR(3X)*
-_tracechtype/\fBcurs_trace\fR(3X)*
-_tracechtype2/\fBcurs_trace\fR(3X)*
-_tracedump/\fBcurs_trace\fR(3X)*
-_tracef/\fBcurs_trace\fR(3X)*
-_tracemouse/\fBcurs_trace\fR(3X)*

 add_wch/\fBcurs_add_wch\fR(3X)
 add_wchnstr/\fBcurs_add_wchstr\fR(3X)
 add_wchstr/\fBcurs_add_wchstr\fR(3X)
 add_wch/\fBcurs_add_wch\fR(3X)
 add_wchnstr/\fBcurs_add_wchstr\fR(3X)
 add_wchstr/\fBcurs_add_wchstr\fR(3X)


@@ -383,6 +372,7 @@ color_content/\fBcurs_color\fR(3X)
 color_set/\fBcurs_attr\fR(3X)
 copywin/\fBcurs_overlay\fR(3X)
 curs_set/\fBcurs_kernel\fR(3X)
 color_set/\fBcurs_attr\fR(3X)
 copywin/\fBcurs_overlay\fR(3X)
 curs_set/\fBcurs_kernel\fR(3X)

+curses_trace/\fBcurs_trace\fR(3X)*

 curses_version/\fBcurs_extend\fR(3X)*
 def_prog_mode/\fBcurs_kernel\fR(3X)
 def_shell_mode/\fBcurs_kernel\fR(3X)
 curses_version/\fBcurs_extend\fR(3X)*
 def_prog_mode/\fBcurs_kernel\fR(3X)
 def_shell_mode/\fBcurs_kernel\fR(3X)


@@ -403,6 +393,8 @@ endwin/\fBcurs_initscr\fR(3X)
 erase/\fBcurs_clear\fR(3X)
 erasechar/\fBcurs_termattrs\fR(3X)
 erasewchar/\fBcurs_termattrs\fR(3X)
 erase/\fBcurs_clear\fR(3X)
 erasechar/\fBcurs_termattrs\fR(3X)
 erasewchar/\fBcurs_termattrs\fR(3X)

+exit_curses/\fBcurs_memleaks\fR(3X)*
+exit_terminfo/\fBcurs_memleaks\fR(3X)*

 extended_color_content/\fBcurs_color\fR(3X)*
 extended_pair_content/\fBcurs_color\fR(3X)*
 extended_slk_color/\fBcurs_slk\fR(3X)*
 extended_color_content/\fBcurs_color\fR(3X)*
 extended_pair_content/\fBcurs_color\fR(3X)*
 extended_slk_color/\fBcurs_slk\fR(3X)*


@@ -441,6 +433,7 @@ has_colors/\fBcurs_color\fR(3X)
 has_ic/\fBcurs_termattrs\fR(3X)
 has_il/\fBcurs_termattrs\fR(3X)
 has_key/\fBcurs_getch\fR(3X)*
 has_ic/\fBcurs_termattrs\fR(3X)
 has_il/\fBcurs_termattrs\fR(3X)
 has_key/\fBcurs_getch\fR(3X)*

+has_mouse/\fBcurs_mouse\fR(3X)*

 hline/\fBcurs_border\fR(3X)
 hline_set/\fBcurs_border_set\fR(3X)
 idcok/\fBcurs_outopts\fR(3X)
 hline/\fBcurs_border\fR(3X)
 hline_set/\fBcurs_border_set\fR(3X)
 idcok/\fBcurs_outopts\fR(3X)


@@ -589,18 +582,19 @@ napms/\fBcurs_kernel\fR(3X)
 newpad/\fBcurs_pad\fR(3X)
 newterm/\fBcurs_initscr\fR(3X)
 newwin/\fBcurs_window\fR(3X)
 newpad/\fBcurs_pad\fR(3X)
 newterm/\fBcurs_initscr\fR(3X)
 newwin/\fBcurs_window\fR(3X)

-nl/\fBcurs_outopts\fR(3X)
+nl/\fBcurs_inopts\fR(3X)

 nocbreak/\fBcurs_inopts\fR(3X)
 nodelay/\fBcurs_inopts\fR(3X)
 noecho/\fBcurs_inopts\fR(3X)
 nofilter/\fBcurs_util\fR(3X)*
 nocbreak/\fBcurs_inopts\fR(3X)
 nodelay/\fBcurs_inopts\fR(3X)
 noecho/\fBcurs_inopts\fR(3X)
 nofilter/\fBcurs_util\fR(3X)*

-nonl/\fBcurs_outopts\fR(3X)
+nonl/\fBcurs_inopts\fR(3X)

 noqiflush/\fBcurs_inopts\fR(3X)
 noraw/\fBcurs_inopts\fR(3X)
 notimeout/\fBcurs_inopts\fR(3X)
 overlay/\fBcurs_overlay\fR(3X)
 overwrite/\fBcurs_overlay\fR(3X)
 pair_content/\fBcurs_color\fR(3X)
 noqiflush/\fBcurs_inopts\fR(3X)
 noraw/\fBcurs_inopts\fR(3X)
 notimeout/\fBcurs_inopts\fR(3X)
 overlay/\fBcurs_overlay\fR(3X)
 overwrite/\fBcurs_overlay\fR(3X)
 pair_content/\fBcurs_color\fR(3X)

+pecho_wchar/\fBcurs_pad\fR(3X)*

 pechochar/\fBcurs_pad\fR(3X)
 pnoutrefresh/\fBcurs_pad\fR(3X)
 prefresh/\fBcurs_pad\fR(3X)
 pechochar/\fBcurs_pad\fR(3X)
 pnoutrefresh/\fBcurs_pad\fR(3X)
 prefresh/\fBcurs_pad\fR(3X)


@@ -611,6 +605,7 @@ qiflush/\fBcurs_inopts\fR(3X)
 raw/\fBcurs_inopts\fR(3X)
 redrawwin/\fBcurs_refresh\fR(3X)
 refresh/\fBcurs_refresh\fR(3X)
 raw/\fBcurs_inopts\fR(3X)
 redrawwin/\fBcurs_refresh\fR(3X)
 refresh/\fBcurs_refresh\fR(3X)

+reset_color_pairs/\fBcurs_color\fR(3X)*

 reset_prog_mode/\fBcurs_kernel\fR(3X)
 reset_shell_mode/\fBcurs_kernel\fR(3X)
 resetty/\fBcurs_kernel\fR(3X)
 reset_prog_mode/\fBcurs_kernel\fR(3X)
 reset_shell_mode/\fBcurs_kernel\fR(3X)
 resetty/\fBcurs_kernel\fR(3X)


@@ -632,7 +627,6 @@ set_term/\fBcurs_initscr\fR(3X)
 setcchar/\fBcurs_getcchar\fR(3X)
 setscrreg/\fBcurs_outopts\fR(3X)
 setsyx/\fBcurs_kernel\fR(3X)
 setcchar/\fBcurs_getcchar\fR(3X)
 setscrreg/\fBcurs_outopts\fR(3X)
 setsyx/\fBcurs_kernel\fR(3X)

-setterm/\fBcurs_terminfo\fR(3X)

 setupterm/\fBcurs_terminfo\fR(3X)
 slk_attr/\fBcurs_slk\fR(3X)*
 slk_attr_off/\fBcurs_slk\fR(3X)
 setupterm/\fBcurs_terminfo\fR(3X)
 slk_attr/\fBcurs_slk\fR(3X)*
 slk_attr_off/\fBcurs_slk\fR(3X)


@@ -650,6 +644,7 @@ slk_refresh/\fBcurs_slk\fR(3X)
 slk_restore/\fBcurs_slk\fR(3X)
 slk_set/\fBcurs_slk\fR(3X)
 slk_touch/\fBcurs_slk\fR(3X)
 slk_restore/\fBcurs_slk\fR(3X)
 slk_set/\fBcurs_slk\fR(3X)
 slk_touch/\fBcurs_slk\fR(3X)

+slk_wset/\fBcurs_slk\fR(3X)*

 standend/\fBcurs_attr\fR(3X)
 standout/\fBcurs_attr\fR(3X)
 start_color/\fBcurs_color\fR(3X)
 standend/\fBcurs_attr\fR(3X)
 standout/\fBcurs_attr\fR(3X)
 start_color/\fBcurs_color\fR(3X)


@@ -781,6 +776,19 @@ wunctrl/\fBcurs_util\fR(3X)
 wvline/\fBcurs_border\fR(3X)
 wvline_set/\fBcurs_border_set\fR(3X)
 .TE
 wvline/\fBcurs_border\fR(3X)
 wvline_set/\fBcurs_border_set\fR(3X)
 .TE

+.PP
+Depending on the configuration,
+additional sets of functions may be available:
+.RS 3
+.TP 5
+\fBcurs_memleaks\fP(3X) - curses memory-leak checking
+.TP 5
+\fBcurs_sp_funcs\fP(3X) - curses screen-pointer extension
+.TP 5
+\fBcurs_threads\fP(3X) - curses thread support
+.TP 5
+\fBcurs_trace\fP(3X) - curses debugging routines
+.RE

 .SH RETURN VALUE
 Routines that return an integer return \fBERR\fR upon failure and an
 integer value other than \fBERR\fR upon successful completion, unless
 .SH RETURN VALUE
 Routines that return an integer return \fBERR\fR upon failure and an
 integer value other than \fBERR\fR upon successful completion, unless


@@ -1297,6 +1305,32 @@ The debug and profiling libraries add a \*(``_g\*(''
 and a \*(``_p\*('' to the root names respectively,
 e.g., \fBlibncurses_g.a\fP and \fBlibncurses_p.a\fP.
 .TP 5
 and a \*(``_p\*('' to the root names respectively,
 e.g., \fBlibncurses_g.a\fP and \fBlibncurses_p.a\fP.
 .TP 5

+\-\-with\-termlib
+Low-level functions which do not depend upon whether the library
+supports wide-characters, are provided in the tinfo library.
+.IP
+By doing this, it is possible to share the tinfo library between
+wide/normal configurations as well as reduce the size of the library
+when only low-level functions are needed.
+.IP
+Those functions are described in these pages:
+.RS
+.bP
+\fBcurs_extend\fP(3X) \- miscellaneous curses extensions
+.bP
+\fBcurs_inopts\fR(3X) \- \fBcurses\fR input options
+.bP
+\fBcurs_kernel\fR(3X) \- low-level \fBcurses\fR routines
+.bP
+\fBcurs_termattrs\fR(3X) \- \fBcurses\fR environment query routines
+.bP
+\fBcurs_termcap\fR(3X) \- \fBcurses\fR emulation of termcap
+.bP
+\fBcurs_terminfo\fR(3X) \- \fBcurses\fR interfaces to terminfo database
+.bP
+\fBcurs_util\fR(3X) \- miscellaneous \fBcurses\fR utility routines
+.RE
+.TP 5

 \-\-with\-trace
 The \fBtrace\fP function normally resides in the debug library,
 but it is sometimes useful to configure this in the shared library.
 \-\-with\-trace
 The \fBtrace\fP function normally resides in the debug library,
 but it is sometimes useful to configure this in the shared library.