X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fncurses.3x;h=df709418e64e3aeaa5f7cfd45bc208652a53b550;hp=9dcdcd940a4c519afdf348a8916a2aacccb7aea7;hb=0948e2c7ac34642a1f8a3a85000933bcbb258cff;hpb=96d6b16de0d487e5d3aed0302a179dbce11b5d96 diff --git a/man/ncurses.3x b/man/ncurses.3x index 9dcdcd94..df709418 100644 --- a/man/ncurses.3x +++ b/man/ncurses.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2009,2010 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.101 2010/12/04 18:38:55 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, @@ -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 @@ -746,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 @@ -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 @@ -852,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 @@ -871,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 @@ -899,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 @@ -930,10 +982,34 @@ and is likely to work for terminal emulators. When setting this variable, you should set it to a nonzero value. Setting it to zero (or to a nonnumber) 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 \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, +.sp +# uxterm with vt100Graphics resource set to false +xterm-utf8|xterm relying on UTF-8 line-graphics, + U8#1, use=xterm, +.fi +.ft +.RE +.IP +The name "U8" is chosen to be two characters, +to permit it to be used by applications that use ncurses' +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 @@ -945,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 @@ -966,33 +1058,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, @@ -1020,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 @@ -1046,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 @@ -1071,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 @@ -1122,6 +1243,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.