ncurses 6.0 - patch 20150606

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

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

-.\" Copyright (c) 1998-2012,2013 Free Software Foundation, Inc.              *
+.\" Copyright (c) 1998-2013,2014 Free Software Foundation, Inc.              *

 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *


@@ -27,9 +27,13 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: ncurses.3x,v 1.110 2013/02/02 22:13:18 tom Exp $
+.\" $Id: ncurses.3x,v 1.119 2014/08/09 20:54:30 tom Exp $

 .hy 0
 .TH ncurses 3X ""
 .hy 0
 .TH ncurses 3X ""

+.ie \n(.g .ds `` \(lq
+.el       .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el       .ds '' ''

 .de bP
 .IP \(bu 4
 ..
 .de bP
 .IP \(bu 4
 ..


@@ -43,7 +47,7 @@
 .SH DESCRIPTION
 The \fBncurses\fR library routines give the user a terminal-independent method
 of updating character screens with reasonable optimization.
 .SH DESCRIPTION
 The \fBncurses\fR library routines give the user a terminal-independent method
 of updating character screens with reasonable optimization.

-This implementation is ``new curses'' (ncurses) and
+This implementation is \*(``new curses\*('' (ncurses) and

 is the approved replacement for
 4.4BSD classic curses, which has been discontinued.
 This describes \fBncurses\fR
 is the approved replacement for
 4.4BSD classic curses, which has been discontinued.
 This describes \fBncurses\fR


@@ -756,14 +760,6 @@ The following environment symbols are useful for customizing the
 runtime behavior of the \fBncurses\fR library.
 The most important ones have been already discussed in detail.
 .TP 5
 runtime behavior of the \fBncurses\fR library.
 The most important ones have been already discussed in detail.
 .TP 5

-BAUDRATE
-The debugging library checks this environment variable when the application
-has redirected output to a file.
-The variable's numeric value is used for the baudrate.
-If no value is found, \fBncurses\fR uses 9600.
-This allows testers to construct repeatable test-cases
-that take into account costs that depend on baudrate.
-.TP 5

 CC
 When set, change occurrences of the command_character
 (i.e., the \fBcmdch\fP capability)
 CC
 When set, change occurrences of the command_character
 (i.e., the \fBcmdch\fP capability)


@@ -774,6 +770,14 @@ Because this name is also used in development environments to represent
 the C compiler's name, \fBncurses\fR ignores it if it does not happen to
 be a single character.
 .TP 5
 the C compiler's name, \fBncurses\fR ignores it if it does not happen to
 be a single character.
 .TP 5

+BAUDRATE
+The debugging library checks this environment variable when the application
+has redirected output to a file.
+The variable's numeric value is used for the baudrate.
+If no value is found, \fBncurses\fR uses 9600.
+This allows testers to construct repeatable test-cases
+that take into account costs that depend on baudrate.
+.TP 5

 COLUMNS
 Specify the width of the screen in characters.
 Applications running in a windowing environment usually are able to
 COLUMNS
 Specify the width of the screen in characters.
 Applications running in a windowing environment usually are able to


@@ -864,6 +868,17 @@ about the colors, set this to "\-1,\-1".
 To make it green-on-black, set it to "2,0".
 Any positive value from zero to the terminfo \fBmax_colors\fR value is allowed.
 .TP 5
 To make it green-on-black, set it to "2,0".
 Any positive value from zero to the terminfo \fBmax_colors\fR value is allowed.
 .TP 5

+NCURSES_CONSOLE2
+This applies only to the MinGW port of ncurses.
+.IP
+The \fBConsole2\fP program's handling of the Microsoft Console API call
+\fBCreateConsoleScreenBuffer\fP is defective.
+Applications which use this will hang.
+However, it is possible to simulate the action of this call by
+mapping coordinates,
+explicitly saving and restoring the original screen contents.
+Setting the environment variable \fBNCGDB\fP has the same effect.
+.TP 5

 NCURSES_GPM_TERMS
 This applies only to ncurses configured to use the GPM interface.
 .IP
 NCURSES_GPM_TERMS
 This applies only to ncurses configured to use the GPM interface.
 .IP


@@ -883,7 +898,7 @@ your terminal driver may not handle these properly.
 Set this environment variable to disable the feature.
 You can also adjust your \fBstty\fP settings to avoid the problem.
 .TP 5
 Set this environment variable to disable the feature.
 You can also adjust your \fBstty\fP settings to avoid the problem.
 .TP 5

-NCURSES_NO_MAGIC_COOKIES
+NCURSES_NO_MAGIC_COOKIE

 Some terminals use a magic-cookie feature which requires special handling
 to make highlighting and other video attributes display properly.
 You can suppress the highlighting entirely for these terminals by
 Some terminals use a magic-cookie feature which requires special handling
 to make highlighting and other video attributes display properly.
 You can suppress the highlighting entirely for these terminals by


@@ -917,13 +932,38 @@ Mandatory padding is used as a part of special control
 sequences such as \fIflash\fR.
 .TP 5
 NCURSES_NO_SETBUF
 sequences such as \fIflash\fR.
 .TP 5
 NCURSES_NO_SETBUF

-Normally \fBncurses\fR enables buffered output during terminal initialization.
-This is done (as in SVr4 curses) for performance reasons.
+This setting is obsolete.
+Before changes
+.RS
+.bP
+started with 5.9 patch 20120825 
+and
+.bP
+continued
+though 5.9 patch 20130126
+.RE
+.IP
+\fBncurses\fR enabled buffered output during terminal initialization.
+This was done (as in SVr4 curses) for performance reasons.

 For testing purposes, both of \fBncurses\fR and certain applications,
 For testing purposes, both of \fBncurses\fR and certain applications,

-this feature is made optional.
+this feature was made optional.

 Setting the NCURSES_NO_SETBUF variable
 Setting the NCURSES_NO_SETBUF variable

-disables output buffering, leaving the output in the original (usually
+disabled output buffering, leaving the output in the original (usually

 line buffered) mode.
 line buffered) mode.

+.IP
+In the current implementation,
+ncurses performs its own buffering and does not require this workaround.
+It does not modify the buffering of the standard output.
+.IP
+The reason for the change was to make the behavior for interrupts and
+other signals more robust.
+One drawback is that certain nonconventional programs would mix
+ordinary stdio calls with ncurses calls and (usually) work.
+This is no longer possible since ncurses is not using
+the buffered standard output but its own output (to the same file descriptor).
+As a special case, the low-level calls such as \fBputp\fP still use the
+standard output.
+But high-level curses calls do not.

 .TP 5
 NCURSES_NO_UTF8_ACS
 During initialization, the \fBncurses\fR library
 .TP 5
 NCURSES_NO_UTF8_ACS
 During initialization, the \fBncurses\fR library


@@ -981,6 +1021,21 @@ file \fBtrace\fR to the current directory.
 TERM
 Denotes your terminal type.
 Each terminal type is distinct, though many are similar.
 TERM
 Denotes your terminal type.
 Each terminal type is distinct, though many are similar.

+.IP
+\fBTERM\fP is commonly set by terminal emulators to help
+applications find a workable terminal description.
+Some of those choose a popular approximation, e.g.,
+\*(``ansi\*('', \*(``vt100\*('', \*(``xterm\*('' rather than an exact fit.
+Not infrequently, your application will have problems with that approach,
+e.g., incorrect function-key definitions.
+.IP
+If you set \fBTERM\fP in your environment,
+it has no effect on the operation of the terminal emulator.
+It only affects the way applications work within the terminal.
+Likewise, as a general rule (\fBxterm\fP being a rare exception),
+terminal emulators which allow you to
+specify \fBTERM\fP as a parameter or configuration value do
+not change their behavior to match that setting.

 .TP 5
 TERMCAP
 If the \fBncurses\fR library has been configured with \fItermcap\fR
 .TP 5
 TERMCAP
 If the \fBncurses\fR library has been configured with \fItermcap\fR


@@ -1102,6 +1157,16 @@ the wide-character library's headers should be installed last,
 to allow applications to be built using either library
 from the same set of headers.
 .TP 5
 to allow applications to be built using either library
 from the same set of headers.
 .TP 5

+\-\-with\-pthread
+The configure script renames the library.
+All of the library names have a "t" appended to them
+(before any "w" added by \fB\-\-enable\-widec\fP).
+.IP
+The global variables such as \fBLINES\fP are replaced by macros to
+allow read-only access.
+At the same time, setter-functions are provided to set these values.
+Some applications (very few) may require changes to work with this convention.
+.TP 5

 \-\-with\-shared
 .TP
 \-\-with\-normal
 \-\-with\-shared
 .TP
 \-\-with\-normal