ncurses 5.9 - patch 20140816
[ncurses.git] / man / ncurses.3x
index 64a0211b352d2db4d786a4249fb7b44dec2f4454..df709418e64e3aeaa5f7cfd45bc208652a53b550 100644 (file)
@@ -1,6 +1,6 @@
 '\" t
 .\"***************************************************************************
-.\" Copyright (c) 1998-2011,2012 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            *
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: ncurses.3x,v 1.107 2012/07/14 21:13:06 tom Exp $
+.\" $Id: ncurses.3x,v 1.119 2014/08/09 20:54:30 tom Exp $
 .hy 0
 .TH ncurses 3X ""
+.ie \n(.g .ds `` \(lq
+.el       .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el       .ds '' ''
 .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.
-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
@@ -55,8 +59,10 @@ and XPG4 (X/Open Portability Guide) curses (also known as XSI curses).
 XSI stands for X/Open System Interfaces Extension.
 The \fBncurses\fR library is freely redistributable in source form.
 Differences from the SVr4
-curses are summarized under the \fBEXTENSIONS\fP and \fBPORTABILITY\fP sections below and
-described in detail in the respective \fBEXTENSIONS\fP, \fBPORTABILITY\fP and \fBBUGS\fP sections
+curses are summarized under the
+\fBEXTENSIONS\fP and \fBPORTABILITY\fP sections below and
+described in detail in the respective
+\fBEXTENSIONS\fP, \fBPORTABILITY\fP and \fBBUGS\fP sections
 of individual man pages.
 .PP
 The \fBncurses\fR library also provides many useful extensions,
@@ -740,7 +746,11 @@ and handle this as an error.
 .PP
 All macros return the value of the \fBw\fR version, except \fBsetscrreg\fR,
 \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and \fBgetmaxyx\fR.
-The return values of \fBsetscrreg\fR, \fBwsetscrreg\fR, \fBgetyx\fR, \fBgetbegyx\fR, and
+The return values of
+\fBsetscrreg\fR,
+\fBwsetscrreg\fR,
+\fBgetyx\fR,
+\fBgetbegyx\fR, and
 \fBgetmaxyx\fR are undefined (i.e., these should not be used as the
 right-hand side of assignment statements).
 .PP
@@ -750,24 +760,24 @@ 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
-BAUDRATE
-The debugging library checks this environment symbol when the application
-has redirected output to a file.
-The symbol'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)
-of the loaded terminfo entries to the value of this symbol.
+of the loaded terminfo entries to the value of this variable.
 Very few terminfo entries provide this feature.
 .IP
 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
+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
@@ -843,8 +853,8 @@ platforms:
 .br
 3 = middle.
 .sp
-This symbol lets you customize the mouse.
-The symbol must be three numeric digits 1\-3 in any order, e.g., 123 or 321.
+This variable lets you customize the mouse.
+The variable must be three numeric digits 1\-3 in any order, e.g., 123 or 321.
 If it is not specified, \fBncurses\fR uses 132.
 .TP 5
 NCURSES_ASSUMED_COLORS
@@ -858,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
+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
@@ -877,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
-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
@@ -905,19 +926,44 @@ have delay times embedded.
 You may wish to use these descriptions,
 but not want to pay the performance penalty.
 .IP
-Set the NCURSES_NO_PADDING symbol to disable all but mandatory
+Set the NCURSES_NO_PADDING environment variable to disable all but mandatory
 padding.
 Mandatory padding is used as a part of special control
 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,
-this feature is made optional.
+this feature was made optional.
 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.
+.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
@@ -942,17 +988,19 @@ ncurses checks for an extended terminfo capability \fBU8\fP.
 This is a numeric capability which can be compiled using \fB@TIC@\ \-x\fP.
 For example
 .RS 5
+.ft CW
 .sp
 .nf
 # linux console, if patched to provide working
 # VT100 shift-in/shift-out, with corresponding font.
 linux-vt100|linux console with VT100 line-graphics,
-       U8#0, use=linux,
+        U8#0, use=linux,
 .sp
 # uxterm with vt100Graphics resource set to false
 xterm-utf8|xterm relying on UTF-8 line-graphics,
-       U8#1, use=xterm,
+        U8#1, use=xterm,
 .fi
+.ft
 .RE
 .IP
 The name "U8" is chosen to be two characters,
@@ -961,7 +1009,7 @@ termcap interface.
 .TP 5
 NCURSES_TRACE
 During initialization, the \fBncurses\fR debugging library
-checks the NCURSES_TRACE symbol.
+checks the NCURSES_TRACE environment variable.
 If it is defined, to a numeric value, \fBncurses\fR calls the \fBtrace\fR
 function, using that value as the argument.
 .IP
@@ -973,15 +1021,31 @@ file \fBtrace\fR to the current directory.
 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
 support, \fBncurses\fR will check for a terminal's description in
 termcap form if it is not available in the terminfo database.
 .IP
-The TERMCAP symbol contains either a terminal description (with
+The TERMCAP environment variable contains either a terminal description (with
 newlines stripped out),
-or a file name telling where the information denoted by the TERM symbol exists.
+or a file name telling where the information denoted by
+the TERM environment variable exists.
 In either case, setting it directs \fBncurses\fR to ignore
 the usual place for this information, e.g., /etc/termcap.
 .TP 5
@@ -994,22 +1058,29 @@ The complete list of directories in order follows:
 .bP
 the last directory to which \fBncurses\fR wrote, if any, is searched first
 .bP
-the directory specified by the TERMINFO symbol
+the directory specified by the TERMINFO environment variable
 .bP
 $HOME/.terminfo
 .bP
-directories listed in the TERMINFO_DIRS symbol
+directories listed in the TERMINFO_DIRS environment variable
 .bP
 one or more directories whose names are configured and compiled into the
-ncurses library, e.g.,
-@TERMINFO@
+ncurses library, i.e.,
+.RS
+.bP
+@TERMINFO_DIRS@ (corresponding to the TERMINFO_DIRS variable)
+.bP
+@TERMINFO@ (corresponding to the TERMINFO variable)
+.RE
 .RE
 .TP 5
 TERMINFO_DIRS
 Specifies a list of directories to search for terminal descriptions.
 The list is separated by colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
-All of the terminal descriptions are in terminfo form, which makes
-a subdirectory named for the first letter of the terminal names therein.
+.IP
+All of the terminal descriptions are in terminfo form.
+Normally these are stored in a directory tree,
+using subdirectories named by the first letter of the terminal names therein.
 .IP
 If \fBncurses\fP is built with a hashed database,
 then each entry in this list can also be the path of the corresponding
@@ -1020,14 +1091,18 @@ directly, then an entry in this list may be the path of a termcap file.
 .TP 5
 TERMPATH
 If TERMCAP does not hold a file name then \fBncurses\fR checks
-the TERMPATH symbol.
-This is a list of filenames separated by spaces or colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
-If the TERMPATH symbol is not set, \fBncurses\fR looks in the files
+the TERMPATH environment variable.
+This is a list of filenames separated by spaces or colons (i.e., ":") on Unix,
+semicolons on OS/2 EMX.
+.IP
+If the TERMPATH environment variable is not set,
+\fBncurses\fR looks in the files
 /etc/termcap, /usr/share/misc/termcap and $HOME/.termcap, in that order.
 .PP
 The library may be configured to disregard the following variables when the
 current user is the superuser (root), or if the application uses setuid or
 setgid permissions:
+.IP
 $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
 .SH ALTERNATE CONFIGURATIONS
 Several different configurations are possible,
@@ -1055,8 +1130,9 @@ It also omits a symbolic link which would allow you to use \fB\-lcurses\fP
 to build executables.
 .TP 5
 \-\-enable\-widec
-The configure script renames the library and (if the \fB\-\-disable\-overwrite\fP
-option is used) puts the header files in a different subdirectory.
+The configure script renames the library and
+(if the \fB\-\-disable\-overwrite\fP option is used)
+puts the header files in a different subdirectory.
 All of the library names have a "w" appended to them,
 i.e., instead of
 .RS
@@ -1081,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
+\-\-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
@@ -1106,8 +1192,8 @@ directory containing initialization files for the terminal capability database
 @TERMINFO@
 terminal capability database
 .SH SEE ALSO
-\fBterminfo\fR(\*n) and related pages whose names begin "curs_" for detailed routine
-descriptions.
+\fBterminfo\fR(\*n) and related pages whose names begin
+"curs_" for detailed routine descriptions.
 .br
 \fBcurs_variables\fR(3X) 
 .SH EXTENSIONS