'\" 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: ncurses.3x,v 1.106 2011/12/17 23:19:59 tom Exp $
+.\" $Id: ncurses.3x,v 1.111 2013/03/02 22:15:25 tom Exp $
.hy 0
.TH ncurses 3X ""
.de bP
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,
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)
.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
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.
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
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
.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
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
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,
.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
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
.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
.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,
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
@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