Vendor import of ncurses 5.9 20140222 snapshot.vendor/ncurses/5.9-20140222

1 files changed, 110 insertions, 38 deletions

diff --git a/man/ncurses.3x b/man/ncurses.3x
index 4acfc050101a..6a5aa7c0c2fe 100644
--- a/man/ncurses.3x
+++ b/man/ncurses.3x
@@ -1,6 +1,6 @@
 '\" t
 .\"***************************************************************************
-.\" Copyright (c) 1998-2010,2011 Free Software Foundation, Inc.              *
+.\" Copyright (c) 1998-2012,2013 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            *
@@ -27,9 +27,13 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: ncurses.3x,v 1.103 2011/02/05 23:21:29 tom Exp $
+.\" $Id: ncurses.3x,v 1.112 2013/07/20 19:29:59 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,
@@ -108,9 +114,9 @@ Most programs would additionally use the sequence:
 .sp
 Before a \fBcurses\fR program is run, the tab stops of the terminal
 should be set and its initialization strings, if defined, must be output.
-This can be done by executing the \fBtput init\fR command
+This can be done by executing the \fB@TPUT@ init\fR command
 after the shell environment variable \fBTERM\fR has been exported.
-\fBtset(1)\fR is usually responsible for doing this.
+\fB@TSET@(1)\fR is usually responsible for doing this.
 [See \fBterminfo\fR(\*n) for further details.]
 .PP
 The \fBncurses\fR library permits manipulation of data structures,
@@ -637,6 +643,7 @@ use_default_colors/\fBdefault_colors\fR(3X)*
 use_env/\fBcurs_util\fR(3X)
 use_extended_names/\fBcurs_extend\fR(3X)*
 use_legacy_coding/\fBlegacy_coding\fR(3X)*
+use_tioctl/\fBcurs_util\fR(3X)
 vid_attr/\fBcurs_terminfo\fR(3X)
 vid_puts/\fBcurs_terminfo\fR(3X)
 vidattr/\fBcurs_terminfo\fR(3X)
@@ -734,9 +741,16 @@ Routines that return an integer return \fBERR\fR upon failure and an
 integer value other than \fBERR\fR upon successful completion, unless
 otherwise noted in the routine descriptions.
 .PP
+As a general rule, routines check for null pointers passed as parameters,
+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
@@ -747,9 +761,9 @@ 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
+The debugging library checks this environment variable when the application
 has redirected output to a file.
-The symbol's numeric value is used for the baudrate.
+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.
@@ -757,7 +771,7 @@ that take into account costs that depend on baudrate.
 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
@@ -786,7 +800,9 @@ For best results, \fBlines\fR and \fBcols\fR should not be specified in
 a terminal description for terminals which are run as emulations.
 .IP
 Use the \fBuse_env\fR function to disable all use of external environment
-(including system calls) to determine the screen size.
+(but not including system calls) to determine the screen size.
+Use the \fBuse_tioctl\fR function to update \fBCOLUMNS\fP or \fBLINES\fP
+to match the screen size obtained from system calls or the terminal database.
 .TP 5
 ESCDELAY
 Specifies the total time, in milliseconds, for which ncurses will
@@ -837,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
@@ -899,19 +915,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
@@ -933,20 +974,22 @@ disables the special check for "linux" and "screen".
 .IP
 As an alternative to the environment variable,
 ncurses checks for an extended terminfo capability \fBU8\fP.
-This is a numeric capability which can be compiled using \fBtic\ \-x\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,
@@ -955,7 +998,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,9 +1016,10 @@ 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
@@ -988,33 +1032,51 @@ 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
+database file.
+.IP
+If \fBncurses\fP is built with a support for reading termcap files
+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,
@@ -1042,8 +1104,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
@@ -1093,8 +1156,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
@@ -1144,6 +1207,15 @@ A small number of local differences (that is, individual differences between
 the XSI Curses and \fBncurses\fR calls) are described in \fBPORTABILITY\fR
 sections of the library man pages.
 .PP
+Unlike other implementations, this one checks parameters such as pointers
+to WINDOW structures to ensure they are not null.
+The main reason for providing this behavior is to guard against programmer
+error.
+The standard interface does not provide a way for the library
+to tell an application which of several possible errors were detected.
+Relying on this (or some other) extension will adversely affect the
+portability of curses applications.
+.PP
 This implementation also contains several extensions:
 .bP
 The routine \fBhas_key\fR is not part of XPG4, nor is it present in SVr4.