X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fncurses.3x.html;h=57ca23abd60f56b817bfe9ca24fb71ae79075250;hp=530b293ac1c87f23be19f7ced997adcf50ff9ced;hb=2e5d72d6396bb38a8d1d1b3534f62e28aebaa600;hpb=f367fa254ce3fe29710c86971f04e03111c2bd2c;ds=sidebyside diff --git a/doc/html/man/ncurses.3x.html b/doc/html/man/ncurses.3x.html index 530b293a..57ca23ab 100644 --- a/doc/html/man/ncurses.3x.html +++ b/doc/html/man/ncurses.3x.html @@ -1,8 +1,8 @@ - +
@@ -60,10 +60,10 @@The ncurses library routines give the user a terminal- independent method of updating character screens with rea- - 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.9 (patch 20120107). + sonable optimization. This implementation is "new curses" + (ncurses) and is the approved replacement for 4.4BSD clas- + sic curses, which has been discontinued. This describes + ncurses version 5.9 (patch 20131221). The ncurses library emulates the curses library of System V Release 4 UNIX, and XPG4 (X/Open Portability Guide) @@ -150,48 +150,48 @@ Among those, the most basic routines are move and addch. More general versions of these routines are included with names beginning with w, allowing the user to specify a - window. The routines not beginning with w affect stdscr. + window. The routines not beginning with w affect stdscr. - After using routines to manipulate a window, refresh is - called, telling curses to make the user's CRT screen look - like stdscr. The characters in a window are actually of - type chtype, (character and attribute data) so that other - information about the character may also be stored with + After using routines to manipulate a window, refresh is + called, telling curses to make the user's CRT screen look + like stdscr. The characters in a window are actually of + type chtype, (character and attribute data) so that other + information about the character may also be stored with each character. - Special windows called pads may also be manipulated. + Special windows called pads may also be manipulated. These are windows which are not constrained to the size of - the screen and whose contents need not be completely dis- + the screen and whose contents need not be completely dis- played. See curs_pad(3x) for more information. - In addition to drawing characters on the screen, video - attributes and colors may be supported, causing the char- - acters to show up in such modes as underlined, in reverse - video, or in color on terminals that support such display + In addition to drawing characters on the screen, video + attributes and colors may be supported, causing the char- + acters to show up in such modes as underlined, in reverse + video, or in color on terminals that support such display enhancements. Line drawing characters may be specified to - be output. On input, curses is also able to translate - arrow and function keys that transmit escape sequences - into single values. The video attributes, line drawing - characters, and input values use names, defined in + be output. On input, curses is also able to translate + arrow and function keys that transmit escape sequences + into single values. The video attributes, line drawing + characters, and input values use names, defined in <curses.h>, such as A_REVERSE, ACS_HLINE, and KEY_LEFT. 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 + if the program is executing in a window environment, line + and column information in the environment will override information read by terminfo. This would affect a program - running in an AT&T 630 layer, for example, where the size + running in an AT&T 630 layer, for example, where the size of a screen is changeable (see ENVIRONMENT). - If the environment variable TERMINFO is defined, any pro- - gram using curses checks for a local terminal definition - before checking in the standard place. For example, if + If the environment variable TERMINFO is defined, any pro- + gram using curses checks for a local terminal definition + before checking in the standard place. For example, if TERM is set to att4424, then the compiled terminal defini- tion is found in /usr/share/terminfo/a/att4424. (The a is copied from the first letter of att4424 to avoid - creation of huge directories.) However, if TERMINFO is + creation of huge directories.) However, if TERMINFO is set to $HOME/myterms, curses first checks $HOME/myterms/a/att4424, @@ -200,119 +200,117 @@ /usr/share/terminfo/a/att4424. - This is useful for developing experimental definitions or + This is useful for developing experimental definitions or when write permission in /usr/share/terminfo is not avail- able. - The integer variables LINES and COLS are defined in - <curses.h> and will be filled in by initscr with the size + The integer variables LINES and COLS are defined in + <curses.h> and will be filled in by initscr with the size of the screen. The constants TRUE and FALSE have the val- ues 1 and 0, respectively. - The curses routines also define the WINDOW * variable + The curses routines also define the WINDOW * variable curscr which is used for certain low-level operations like - clearing and redrawing a screen containing garbage. The + clearing and redrawing a screen containing garbage. The curscr can be used in only a few routines. Routine and Argument Names - Many curses routines have two or more versions. The rou- + Many curses routines have two or more versions. The rou- tines prefixed with w require a window argument. The rou- tines prefixed with p require a pad argument. Those with- out a prefix generally use stdscr. The routines prefixed with mv require a y and x coordinate - to move to before performing the appropriate action. The - mv routines imply a call to move before the call to the - other routine. The coordinate y always refers to the row - (of the window), and x always refers to the column. The + to move to before performing the appropriate action. The + mv routines imply a call to move before the call to the + other routine. The coordinate y always refers to the row + (of the window), and x always refers to the column. The upper left-hand corner is always (0,0), not (1,1). The routines prefixed with mvw take both a window argument - and x and y coordinates. The window argument is always + and x and y coordinates. The window argument is always specified before the coordinates. - In each case, win is the window affected, and pad is the + In each case, win is the window affected, and pad is the pad affected; win and pad are always pointers to type WIN- DOW. Option setting routines require a Boolean flag bf with the - 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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- + 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- + 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, + stores a "wide" character. Like chtype, this may be an integer. wint_t - stores a wchar_t or WEOF - not the same, + 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 + 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 - of the manual page on which it is described. Routines - flagged with `*' are ncurses-specific, not described by + of the manual page on which it is described. Routines + flagged with `*' are ncurses-specific, not described by XPG4 or present in SVr4. - curses Routine Name Manual Page Name -------------------------------------------- COLOR_PAIR curs_color(3x) PAIR_NUMBER curs_attr(3x) _nc_free_and_exit curs_memleaks(3x)* - _nc_freeall curs_memleaks(3x)* _nc_tracebits curs_trace(3x)* + _traceattr curs_trace(3x)* _traceattr2 curs_trace(3x)* _tracechar curs_trace(3x)* @@ -376,9 +374,9 @@ echo curs_inopts(3x) echo_wchar curs_add_wch(3x) echochar curs_addch(3x) - endwin curs_initscr(3x) erase curs_clear(3x) + erasechar curs_termattrs(3x) erasewchar curs_termattrs(3x) filter curs_util(3x) @@ -442,9 +440,9 @@ 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)* @@ -508,9 +506,9 @@ mvinsch curs_insch(3x) mvinsnstr curs_insstr(3x) mvinsstr curs_insstr(3x) - mvinstr curs_instr(3x) mvinwstr curs_inwstr(3x) + mvprintw curs_printw(3x) mvscanw curs_scanw(3x) mvvline curs_border(3x) @@ -574,9 +572,9 @@ pair_content curs_color(3x) pechochar curs_pad(3x) pnoutrefresh curs_pad(3x) - prefresh curs_pad(3x) printw curs_printw(3x) + putp curs_terminfo(3x) putwin curs_util(3x) qiflush curs_inopts(3x) @@ -640,9 +638,9 @@ tigetstr curs_terminfo(3x) timeout curs_inopts(3x) touchline curs_touch(3x) - touchwin curs_touch(3x) tparm curs_terminfo(3x) + tputs curs_termcap(3x) tputs curs_terminfo(3x) trace curs_trace(3x)* @@ -656,6 +654,7 @@ use_env curs_util(3x) use_extended_names curs_extend(3x)* use_legacy_coding legacy_coding(3x)* + use_tioctl curs_util(3x) vid_attr curs_terminfo(3x) vid_puts curs_terminfo(3x) vidattr curs_terminfo(3x) @@ -706,8 +705,8 @@ wgetbkgrnd curs_bkgrnd(3x) wgetch curs_getch(3x) wgetn_wstr curs_get_wstr(3x) - wgetnstr curs_getstr(3x) + wgetstr curs_getstr(3x) whline curs_border(3x) whline_set curs_border_set(3x) @@ -752,17 +751,17 @@
- Routines that return an integer return ERR upon failure - and an integer value other than ERR upon successful com- - pletion, unless otherwise noted in the routine descrip- + Routines that return an integer return ERR upon failure + and an integer value other than ERR upon successful com- + pletion, unless otherwise noted in the routine descrip- tions. As a general rule, routines check for null pointers passed as parameters, and handle this as an error. - All macros return the value of the w version, except + All macros return the value of the w version, except setscrreg, wsetscrreg, getyx, getbegyx, and getmaxyx. The - return values of setscrreg, wsetscrreg, getyx, getbegyx, + return values of setscrreg, wsetscrreg, getyx, getbegyx, and getmaxyx are undefined (i.e., these should not be used as the right-hand side of assignment statements). @@ -776,16 +775,17 @@ important ones have been already discussed in detail. 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, ncurses uses 9600. This allows - testers to construct repeatable test-cases that take - into account costs that depend on baudrate. + The debugging library checks this environment vari- + able when the application has redirected output to a + file. The variable's numeric value is used for the + baudrate. If no value is found, ncurses 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 cmdch capability) of the loaded terminfo - entries to the value of this symbol. Very few ter- + entries to the value of this variable. Very few ter- minfo entries provide this feature. Because this name is also used in development envi- @@ -820,39 +820,42 @@ as emulations. Use the use_env function to disable all use of exter- - nal environment (including system calls) to determine - the screen size. + nal environment (but not including system calls) to + determine the screen size. Use the use_tioctl func- + tion to update COLUMNS or LINES to match the screen + size obtained from system calls or the terminal data- + base. ESCDELAY - Specifies the total time, in milliseconds, for which - ncurses will await a character sequence, e.g., a - function key. The default value, 1000 milliseconds, + Specifies the total time, in milliseconds, for which + ncurses will await a character sequence, e.g., a + function key. The default value, 1000 milliseconds, is enough for most uses. However, it is made a vari- able to accommodate unusual applications. The most common instance where you may wish to change - this value is to work with slow hosts, e.g., running - on a network. If the host cannot read characters - rapidly enough, it will have the same effect as if - the terminal did not send characters rapidly enough. + this value is to work with slow hosts, e.g., running + on a network. If the host cannot read characters + rapidly enough, it will have the same effect as if + the terminal did not send characters rapidly enough. The library will still see a timeout. - Note that xterm mouse events are built up from char- - acter sequences received from the xterm. If your + Note that xterm mouse events are built up from char- + acter sequences received from the xterm. If your application makes heavy use of multiple-clicking, you - may wish to lengthen this default value because the - timeout applies to the composed multi-click event as + may wish to lengthen this default value because the + timeout applies to the composed multi-click event as well as the individual clicks. - In addition to the environment variable, this imple- - mentation provides a global variable with the same + In addition to the environment variable, this imple- + mentation provides a global variable with the same name. Portable applications should not rely upon the - presence of ESCDELAY in either form, but setting the - environment variable rather than the global variable - does not create problems when compiling an applica- + presence of ESCDELAY in either form, but setting the + environment variable rather than the global variable + does not create problems when compiling an applica- tion. - HOME Tells ncurses where your home directory is. That is + HOME Tells ncurses where your home directory is. That is where it may read and write auxiliary terminal descriptions: @@ -860,8 +863,8 @@ $HOME/.terminfo LINES - Like COLUMNS, specify the height of the screen in - characters. See COLUMNS for a detailed description. + Like COLUMNS, specify the height of the screen in + characters. See COLUMNS for a detailed description. MOUSE_BUTTONS_123 This applies only to the OS/2 EMX port. It specifies @@ -872,10 +875,10 @@ 2 = right 3 = middle. - This symbol lets you customize the mouse. The symbol - must be three numeric digits 1-3 in any order, e.g., - 123 or 321. If it is not specified, ncurses uses - 132. + 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, + ncurses uses 132. NCURSES_ASSUMED_COLORS Override the compiled-in assumption that the termi- @@ -913,8 +916,8 @@ 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 setting this environment variable. + suppress the highlighting entirely for these termi- + nals by setting this environment variable. NCURSES_NO_PADDING Most of the terminal descriptions in the terminfo @@ -939,19 +942,41 @@ to use these descriptions, but not want to pay the performance penalty. - Set the NCURSES_NO_PADDING symbol to disable all but - mandatory padding. Mandatory padding is used as a - part of special control sequences such as flash. + 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 flash. NCURSES_NO_SETBUF - Normally ncurses enables buffered output during ter- - minal initialization. This is done (as in SVr4 - curses) for performance reasons. For testing pur- - poses, both of ncurses and certain applications, this - feature is made optional. Setting the - NCURSES_NO_SETBUF variable disables output buffering, - leaving the output in the original (usually line - buffered) mode. + This setting is obsolete. Before changes + + o started with 5.9 patch 20120825 and + + o continued though 5.9 patch 20130126 + + ncurses enabled buffered output during terminal ini- + tialization. This was done (as in SVr4 curses) for + performance reasons. For testing purposes, both of + ncurses and certain applications, this feature was + made optional. Setting the NCURSES_NO_SETBUF vari- + able disabled output buffering, leaving the output in + the original (usually line buffered) mode. + + In the current implementation, ncurses performs its + own buffering and does not require this workaround. + It does not modify the buffering of the standard out- + put. + + 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 putp still + use the standard output. But high-level curses calls + do not. NCURSES_NO_UTF8_ACS During initialization, the ncurses library checks for @@ -981,11 +1006,11 @@ # 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, # uxterm with vt100Graphics resource set to false xterm-utf8|xterm relying on UTF-8 line-graphics, - U8#1, use=xterm, + U8#1, use=xterm, The name "U8" is chosen to be two characters, to per- mit it to be used by applications that use ncurses' @@ -993,9 +1018,9 @@ NCURSES_TRACE During initialization, the ncurses debugging library - checks the NCURSES_TRACE symbol. If it is defined, - to a numeric value, ncurses calls the trace function, - using that value as the argument. + checks the NCURSES_TRACE environment variable. If it + is defined, to a numeric value, ncurses calls the + trace function, using that value as the argument. The argument values, which are defined in curses.h, provide several types of information. When running @@ -1011,12 +1036,12 @@ description in termcap form if it is not available in the terminfo database. - The TERMCAP symbol contains either a terminal - description (with newlines stripped out), or a file - name telling where the information denoted by the - TERM symbol exists. In either case, setting it - directs ncurses to ignore the usual place for this - information, e.g., /etc/termcap. + 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 environment variable exists. In either + case, setting it directs ncurses to ignore the usual + place for this information, e.g., /etc/termcap. TERMINFO Overrides the directory in which ncurses searches for @@ -1027,23 +1052,33 @@ o the last directory to which ncurses wrote, if any, is searched first - o the directory specified by the TERMINFO symbol + o the directory specified by the TERMINFO environ- + ment variable o $HOME/.terminfo - o directories listed in the TERMINFO_DIRS symbol + o directories listed in the TERMINFO_DIRS environ- + ment variable o one or more directories whose names are config- - ured and compiled into the ncurses library, e.g., - /usr/share/terminfo + ured and compiled into the ncurses library, i.e., + + o /usr/local/ncurses/share/ter- + minfo:/usr/share/terminfo (corresponding to + the TERMINFO_DIRS variable) + + o /usr/share/terminfo (corresponding to the + TERMINFO variable) TERMINFO_DIRS Specifies a list of directories to search for termi- nal 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. + (i.e., ":") on Unix, semicolons on OS/2 EMX. + + 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. If ncurses is built with a hashed database, then each entry in this list can also be the path of the corre- @@ -1055,17 +1090,21 @@ TERMPATH If TERMCAP does not hold a file name then ncurses - 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, + checks the TERMPATH environment variable. This is a + list of filenames separated by spaces or colons + (i.e., ":") on Unix, semicolons on OS/2 EMX. + + If the TERMPATH environment variable 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), - or if the application uses setuid or setgid permissions: - $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME. + or if the application uses setuid or setgid permissions: + + $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as + $HOME.@@ -1126,10 +1165,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 @@ -1247,31 +1286,31 @@ o This implementation can also be configured to provide a set of functions which improve the ability to manage - multiple screens. See curs_sp_funcs(3x) for details. + multiple screens. See curs_sp_funcs(3x) for details. - 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 sending NUL bytes. This - method is slightly more expensive, but narrows the inter- - face to the UNIX kernel significantly and increases the + 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.
- 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.
- 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.