X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fncurses.3x;h=df709418e64e3aeaa5f7cfd45bc208652a53b550;hp=64a0211b352d2db4d786a4249fb7b44dec2f4454;hb=0948e2c7ac34642a1f8a3a85000933bcbb258cff;hpb=26001c55f3e698f2467ee6e4a6c376bed9be6439 diff --git a/man/ncurses.3x b/man/ncurses.3x index 64a0211b..df709418 100644 --- a/man/ncurses.3x +++ b/man/ncurses.3x @@ -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 * @@ -27,9 +27,13 @@ .\" 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