X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fncurses.3x.html;h=8b1dee843247a8907e220114fabf8401d17d93d8;hb=3511767aa77f332927de0c4a610f9fb37ea18101;hp=c42513ab55f8ede63c33eaff164ccd50268a5634;hpb=027ae42953e3186daed8f3882da73de48291b606;p=ncurses.git
diff --git a/doc/html/man/ncurses.3x.html b/doc/html/man/ncurses.3x.html
index c42513ab..8b1dee84 100644
--- a/doc/html/man/ncurses.3x.html
+++ b/doc/html/man/ncurses.3x.html
@@ -2,7 +2,7 @@
@@ -63,16 +63,22 @@
sonable optimization. This implementation is ``new
curses'' (ncurses) and is the approved replacement for
4.4BSD classic curses, which has been discontinued. This
- describes ncurses version 5.5 (patch 20061209).
-
- The ncurses routines emulate the curses(3x) library of
- System V Release 4 UNIX, and the XPG4 curses standard (XSI
- curses) but the ncurses library is freely redistributable
- in source form. Differences from the SVr4 curses are sum-
- marized under the EXTENSIONS and PORTABILITY sections
- below and described in detail in the respective EXTEN-
- SIONS, PORTABILITY and BUGS sections of individual man
- pages.
+ describes ncurses version 5.6 (patch 20081011).
+
+ The ncurses library emulates the curses(3x) library of
+ System V Release 4 UNIX, and XPG4 (X/Open Portability
+ Guide) curses (also known as XSI curses). XSI stands for
+ X/Open System Interfaces Extension. The ncurses library
+ is freely redistributable in source form. Differences
+ from the SVr4 curses are summarized under the EXTENSIONS
+ and PORTABILITY sections below and described in detail in
+ the respective EXTENSIONS, PORTABILITY and BUGS sections
+ of individual man pages.
+
+ The ncurses library also provides many useful extensions,
+ i.e., features which cannot be implemented by a simple
+ add-on library but which require access to the internals
+ of the library.
A program using these routines must be linked with the
-lncurses option, or (if it has been generated) with the
@@ -90,13 +96,25 @@
lation; use of soft label keys; terminfo capabilities; and
access to low-level terminal-manipulation routines.
- To initialize the routines, the routine initscr or newterm
- must be called before any of the other routines that deal
- with windows and screens are used. The routine endwin
- must be called before exiting. To get character-at-a-time
- input without echoing (most interactive, screen oriented
- programs want this), the following sequence should be
- used:
+ The library uses the locale which the calling program has
+ initialized. That is normally done with setlocale:
+
+ setlocale(LC_ALL, "");
+
+ If the locale is not initialized, the library assumes that
+ characters are printable as in ISO-8859-1, to work with
+ certain legacy programs. You should initialize the locale
+ and not rely on specific details of the library when the
+ locale has not been setup.
+
+ The function initscr or newterm must be called to initial-
+ ize the library before any of the other routines that deal
+ with windows and screens are used. The routine endwin
+ must be called before exiting.
+
+ To get character-at-a-time input without echoing (most
+ interactive, screen oriented programs want this), the fol-
+ lowing sequence should be used:
initscr(); cbreak(); noecho();
@@ -121,9 +139,9 @@
be created with newwin.
Note that curses does not handle overlapping windows,
- that's done by the panel(3x) library. This means that you
+ that's done by the panel(3x) library. This means that you
can either use stdscr or divide the screen into tiled win-
- dows and not using stdscr at all. Mixing the two will
+ dows and not using stdscr at all. Mixing the two will
result in unpredictable, and undesired, effects.
Windows are referred to by variables declared as WINDOW *.
@@ -160,7 +178,7 @@
If the environment variables LINES and COLUMNS are set, or
if the program is executing in a window environment, line
and column information in the environment will override
- information read by terminfo. This would effect a program
+ information read by terminfo. This would affect a program
running in an AT&T 630 layer, for example, where the size
of a screen is changeable (see ENVIRONMENT).
@@ -218,11 +236,67 @@
DOW.
Option setting routines require a Boolean flag bf with the
- value TRUE or FALSE; bf is always of type bool. The vari-
- ables ch and attrs below are always of type chtype. The
- types WINDOW, SCREEN, bool, and chtype are defined in
- <curses.h>. The type TERMINAL is defined in <term.h>.
- All other arguments are integers.
+ value TRUE or FALSE; bf is always of type bool. Most of
+ the data types used in the library routines, such as WIN-
+ DOW, SCREEN, bool, and chtype are defined in <curses.h>.
+ Types used for the terminfo routines such as TERMINAL are
+ defined in <term.h>.
+
+ This manual page describes functions which may appear in
+ any configuration of the library. There are two common
+ configurations of the library:
+
+ ncurses
+ the "normal" library, which handles 8-bit
+ characters. The normal (8-bit) library stores
+ characters combined with attributes in chtype
+ data.
+
+ Attributes alone (no corresponding character)
+ may be stored in chtype or the equivalent
+ attr_t data. In either case, the data is
+ stored in something like an integer.
+
+ Each cell (row and column) in a WINDOW is
+ stored as a chtype.
+
+ ncursesw
+ the so-called "wide" library, which handles
+ multibyte characters (See the section on
+ ALTERNATE CONFIGURATIONS). The "wide" library
+ includes all of the calls from the "normal"
+ library. It adds about one third more calls
+ using data types which store multibyte charac-
+ ters:
+
+ cchar_t
+ corresponds to chtype. However it is a
+ structure, because more data is stored
+ than can fit into an integer. The char-
+ acters are large enough to require a full
+ integer value - and there may be more
+ than one character per cell. The video
+ attributes and color are stored in sepa-
+ rate fields of the structure.
+
+ Each cell (row and column) in a WINDOW is
+ stored as a cchar_t.
+
+ wchar_t
+ stores a "wide" character. Like chtype,
+ this may be an integer.
+
+ wint_t
+ stores a wchar_t or WEOF - not the same,
+ though both may have the same size.
+
+ The "wide" library provides new functions
+ which are analogous to functions in the "nor-
+ mal" library. There is a naming convention
+ which relates many of the normal/wide vari-
+ ants: a "_w" is inserted into the name. For
+ example, waddch becomes wadd_wch.
+
Routine Name Index
The following table lists each curses routine and the name
@@ -236,6 +310,7 @@
COLOR_PAIR curs_color(3x)
PAIR_NUMBER curs_attr(3x)
_nc_tracebits curs_trace(3x)*
+
_traceattr curs_trace(3x)*
_traceattr2 curs_trace(3x)*
_tracechar curs_trace(3x)*
@@ -244,7 +319,6 @@
_tracedump curs_trace(3x)*
_tracef curs_trace(3x)*
_tracemouse curs_trace(3x)*
-
add_wch curs_add_wch(3x)
add_wchnstr curs_add_wchstr(3x)
add_wchstr curs_add_wchstr(3x)
@@ -302,6 +376,7 @@
echochar curs_addch(3x)
endwin curs_initscr(3x)
erase curs_clear(3x)
+
erasechar curs_termattrs(3x)
erasewchar curs_termattrs(3x)
filter curs_util(3x)
@@ -309,16 +384,24 @@
flushinp curs_util(3x)
get_wch curs_get_wch(3x)
get_wstr curs_get_wstr(3x)
+ getattrs curs_attr(3x)
+ getbegx curs_legacy(3x)*
+ getbegy curs_legacy(3x)*
getbegyx curs_getyx(3x)
-
getbkgd curs_bkgd(3x)
getbkgrnd curs_bkgrnd(3x)
getcchar curs_getcchar(3x)
getch curs_getch(3x)
+ getcurx curs_legacy(3x)*
+ getcury curs_legacy(3x)*
+ getmaxx curs_legacy(3x)*
+ getmaxy curs_legacy(3x)*
getmaxyx curs_getyx(3x)
getmouse curs_mouse(3x)*
getn_wstr curs_get_wstr(3x)
getnstr curs_getstr(3x)
+ getparx curs_legacy(3x)*
+ getpary curs_legacy(3x)*
getparyx curs_getyx(3x)
getstr curs_getstr(3x)
getsyx curs_kernel(3x)
@@ -356,7 +439,19 @@
instr curs_instr(3x)
intrflush curs_inopts(3x)
inwstr curs_inwstr(3x)
+ is_cleared curs_opaque(3x)*
+ is_idcok curs_opaque(3x)*
+ is_idlok curs_opaque(3x)*
+
+ is_immedok curs_opaque(3x)*
+ is_keypad curs_opaque(3x)*
+ is_leaveok curs_opaque(3x)*
is_linetouched curs_touch(3x)
+ is_nodelay curs_opaque(3x)*
+ is_notimeout curs_opaque(3x)*
+ is_scrollok curs_opaque(3x)*
+ is_syncok curs_opaque(3x)*
+ is_term_resized resizeterm(3x)*
is_wintouched curs_touch(3x)
isendwin curs_initscr(3x)
key_defined key_defined(3x)*
@@ -376,7 +471,6 @@
mousemask curs_mouse(3x)*
move curs_move(3x)
mvadd_wch curs_add_wch(3x)
-
mvadd_wchnstr curs_add_wchstr(3x)
mvadd_wchstr curs_add_wchstr(3x)
mvaddch curs_addch(3x)
@@ -414,6 +508,7 @@
mvinsstr curs_insstr(3x)
mvinstr curs_instr(3x)
mvinwstr curs_inwstr(3x)
+
mvprintw curs_printw(3x)
mvscanw curs_scanw(3x)
mvvline curs_border(3x)
@@ -442,7 +537,6 @@
mvwin_wch curs_in_wch(3x)
mvwin_wchnstr curs_in_wchstr(3x)
mvwin_wchstr curs_in_wchstr(3x)
-
mvwinch curs_inch(3x)
mvwinchnstr curs_inchstr(3x)
mvwinchstr curs_inchstr(3x)
@@ -468,6 +562,7 @@
nocbreak curs_inopts(3x)
nodelay curs_inopts(3x)
noecho curs_inopts(3x)
+ nofilter curs_util(3x)*
nonl curs_outopts(3x)
noqiflush curs_inopts(3x)
noraw curs_inopts(3x)
@@ -479,6 +574,7 @@
pnoutrefresh curs_pad(3x)
prefresh curs_pad(3x)
printw curs_printw(3x)
+
putp curs_terminfo(3x)
putwin curs_util(3x)
qiflush curs_inopts(3x)
@@ -508,7 +604,6 @@
setterm curs_terminfo(3x)
setupterm curs_terminfo(3x)
slk_attr curs_slk(3x)*
-
slk_attr_off curs_slk(3x)
slk_attr_on curs_slk(3x)
slk_attr_set curs_slk(3x)
@@ -545,6 +640,7 @@
touchline curs_touch(3x)
touchwin curs_touch(3x)
tparm curs_terminfo(3x)
+
tputs curs_termcap(3x)
tputs curs_terminfo(3x)
trace curs_trace(3x)*
@@ -557,6 +653,7 @@
use_default_colors default_colors(3x)*
use_env curs_util(3x)
use_extended_names curs_extend(3x)*
+ use_legacy_coding legacy_coding(3x)*
vid_attr curs_terminfo(3x)
vid_puts curs_terminfo(3x)
vidattr curs_terminfo(3x)
@@ -574,7 +671,6 @@
waddchnstr curs_addchstr(3x)
waddchstr curs_addchstr(3x)
waddnstr curs_addstr(3x)
-
waddnwstr curs_addwstr(3x)
waddstr curs_addstr(3x)
waddwstr curs_addwstr(3x)
@@ -610,6 +706,7 @@
wgetn_wstr curs_get_wstr(3x)
wgetnstr curs_getstr(3x)
wgetstr curs_getstr(3x)
+
whline curs_border(3x)
whline_set curs_border_set(3x)
win_wch curs_in_wch(3x)
@@ -640,7 +737,6 @@
wscanw curs_scanw(3x)
wscrl curs_scroll(3x)
wsetscrreg curs_outopts(3x)
-
wstandend curs_attr(3x)
wstandout curs_attr(3x)
wsyncdown curs_window(3x)
@@ -774,14 +870,27 @@
NCURSES_ASSUMED_COLORS
Override the compiled-in assumption that the termi-
nal's default colors are white-on-black (see
- assume_default_colors(3x)). You may set the fore-
- ground and background color values with this environ-
- ment variable by proving a 2-element list:
- foreground,background. For example, to tell ncurses
- to not assume anything 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 max_col-
- ors value is allowed.
+ default_colors(3x)). You may set the foreground and
+ background color values with this environment vari-
+ able by proving a 2-element list: foreground,back-
+ ground. For example, to tell ncurses to not assume
+ anything about the colors, set this to "-1,-1". To
+ make it green-on-black, set it to "2,0". Any posi-
+ tive value from zero to the terminfo max_colors value
+ is allowed.
+
+ NCURSES_GPM_TERMS
+ This applies only to ncurses configured to use the
+ GPM interface.
+
+ If present, the environment variable is a list of one
+ or more terminal names against which the TERM envi-
+ ronment variable is matched. Setting it to an empty
+ value disables the GPM interface; using the built-in
+ support for xterm, etc.
+
+ If the environment variable is absent, ncurses will
+ attempt to open GPM if TERM contains "linux".
NCURSES_NO_HARD_TABS
Ncurses may use tabs as part of the cursor movement
@@ -801,19 +910,19 @@
Most of the terminal descriptions in the terminfo
database are written for real "hardware" terminals.
Many people use terminal emulators which run in a
- windowing environment and use curses-based applica-
- tions. Terminal emulators can duplicate all of the
- important aspects of a hardware terminal, but they do
- not have the same limitations. The chief limitation
- of a hardware terminal from the standpoint of your
- application is the management of dataflow, i.e., tim-
- ing. Unless a hardware terminal is interfaced into a
- terminal concentrator (which does flow control), it
- (or your application) must manage dataflow, prevent-
- ing overruns. The cheapest solution (no hardware
- cost) is for your program to do this by pausing after
- operations that the terminal does slowly, such as
- clearing the display.
+ windowing environment and use curses-based
+ applications. Terminal emulators can duplicate all
+ of the important aspects of a hardware terminal, but
+ they do not have the same limitations. The chief
+ limitation of a hardware terminal from the standpoint
+ of your application is the management of dataflow,
+ i.e., timing. Unless a hardware terminal is inter-
+ faced into a terminal concentrator (which does flow
+ control), it (or your application) must manage
+ dataflow, preventing overruns. The cheapest solution
+ (no hardware cost) is for your program to do this by
+ pausing after operations that the terminal does
+ slowly, such as clearing the display.
As a result, many terminal descriptions (including
the vt100) have delay times embedded. You may wish
@@ -909,12 +1018,12 @@
TERMPATH
If TERMCAP does not hold a file name then ncurses
- 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, ncurses looks in the files
- /etc/termcap, /usr/share/misc/termcap and
- $HOME/.termcap, in that order.
+ checks the TERMPATH symbol. This is a list of file-
+ names separated by spaces or colons (i.e., ":") on
+ Unix, semicolons on OS/2 EMX. If the TERMPATH symbol
+ is not set, ncurses looks in the files /etc/termcap,
+ /usr/share/misc/termcap and $HOME/.termcap, in that
+ order.
The library may be configured to disregard the following
variables when the current user is the superuser (root),
@@ -980,10 +1089,10 @@
--with-profile
The shared and normal (static) library names differ
- by their suffixes, e.g., libncurses.so and
- libncurses.a. The debug and profiling libraries add
- a "_g" and a "_p" to the root names respectively,
- e.g., libncurses_g.a and libncurses_p.a.
+ by their suffixes, e.g., libncurses.so and libn-
+ curses.a. The debug and profiling libraries add a
+ "_g" and a "_p" to the root names respectively, e.g.,
+ libncurses_g.a and libncurses_p.a.
--with-trace
The trace function normally resides in the debug
@@ -1018,7 +1127,7 @@
in core and startup cycles.
The ncurses library includes facilities for capturing
- mouse events on certain terminals (including xterm). See
+ mouse events on certain terminals (including xterm). See
the curs_mouse(3x) manual page for details.
The ncurses library includes facilities for responding to
@@ -1050,57 +1159,65 @@
PORTABILITY
The ncurses library is intended to be BASE-level confor-
- mant with the XSI Curses standard. The EXTENDED XSI
- Curses functionality (including color support) is sup-
- ported.
+ mant with XSI Curses. The EXTENDED XSI Curses functional-
+ ity (including color support) is supported.
- A small number of local differences (that is, individual
- differences between the XSI Curses and ncurses calls) are
- described in PORTABILITY sections of the library man
+ A small number of local differences (that is, individual
+ differences between the XSI Curses and ncurses calls) are
+ described in PORTABILITY sections of the library man
pages.
- The routine has_key is not part of XPG4, nor is it present
- in SVr4. See the curs_getch(3x) manual page for details.
+ This implementation also contains several extensions:
+
+ The routine has_key is not part of XPG4, nor is it
+ present in SVr4. See the curs_getch(3x) manual page
+ for details.
+
+ The routine slk_attr is not part of XPG4, nor is it
+ present in SVr4. See the curs_slk(3x) manual page
+ for details.
- The routine slk_attr is not part of XPG4, nor is it
- present in SVr4. See the curs_slk(3x) manual page for
- details.
+ The routines getmouse, mousemask, ungetmouse, mou-
+ seinterval, and wenclose relating to mouse interfac-
+ ing are not part of XPG4, nor are they present in
+ SVr4. See the curs_mouse(3x) manual page for
+ details.
- The routines getmouse, mousemask, ungetmouse, mouseinter-
- val, and wenclose relating to mouse interfacing are not
- part of XPG4, nor are they present in SVr4. See the
- curs_mouse(3x) manual page for details.
+ The routine mcprint was not present in any previous
+ curses implementation. See the curs_print(3x) manual
+ page for details.
- The routine mcprint was not present in any previous curses
- implementation. See the curs_print(3x) manual page for
- details.
+ The routine wresize is not part of XPG4, nor is it
+ present in SVr4. See the wresize(3x) manual page for
+ details.
- The routine wresize is not part of XPG4, nor is it present
- in SVr4. See the wresize(3x) manual page for details.
+ The WINDOW structure's internal details can be hidden
+ from application programs. See curs_opaque(3x) for
+ the discussion of is_scrollok, etc.
- In historic curses versions, delays embedded in the capa-
+ In historic curses versions, delays embedded in the capa-
bilities cr, ind, cub1, ff and tab activated corresponding
- delay bits in the UNIX tty driver. In this implementa-
- tion, all padding is done by NUL sends. This method is
- slightly more expensive, but narrows the interface to the
- UNIX kernel significantly and increases the package's
- portability correspondingly.
+ delay bits in the UNIX tty driver. In this implementa-
+ tion, all padding is done by sending NUL bytes. This
+ method is slightly more expensive, but narrows the inter-
+ face to the UNIX kernel significantly and increases the
+ package's portability correspondingly.
NOTES
- The header file <curses.h> automatically includes the
+ The header file <curses.h> automatically includes the
header files <stdio.h> and <unctrl.h>.
- If standard output from a ncurses program is re-directed
- to something which is not a tty, screen updates will be
+ If standard output from a ncurses program is re-directed
+ to something which is not a tty, screen updates will be
directed to standard error. This was an undocumented fea-
ture of AT&T System V Release 3 curses.
AUTHORS
- Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
+ Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
Based on pcurses by Pavel Curtis.