X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fncurses.3x;h=26a2aac3e3175797a87b7cac4f4288476cd050c0;hp=22509fa1ace6b963f3b0c46ecf33d40b60f7ffe4;hb=eee1237c858e39ddc0970dfc5a44d0ec76e2d9e4;hpb=8e25fff6a5f576b6dc35eb02b9783fa58680d07b

diff --git a/man/ncurses.3x b/man/ncurses.3x
index 22509fa1..26a2aac3 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,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: ncurses.3x,v 1.105 2011/07/30 23:38:59 tom Exp $
+.\" $Id: ncurses.3x,v 1.110 2013/02/02 22:13:18 tom Exp $
 .hy 0
 .TH ncurses 3X ""
 .de bP
@@ -55,8 +55,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 +110,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 +639,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)
@@ -739,7 +742,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,9 +757,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.
@@ -760,7 +767,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
@@ -789,7 +796,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
@@ -840,8 +849,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
@@ -902,7 +911,7 @@ 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.
@@ -936,20 +945,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,
@@ -958,7 +969,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
@@ -976,9 +987,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
@@ -991,22 +1003,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
@@ -1017,14 +1036,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,
@@ -1052,8 +1075,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
@@ -1103,8 +1127,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