ncurses man page on OpenBSD

Man page or keyword search:  
man Server   11362 pages
apropos Keyword Search (all sections)
Output format
OpenBSD logo
[printable version]

ncurses(3)							    ncurses(3)

NAME
       ncurses - CRT screen handling and optimization package

SYNOPSIS
       #include <curses.h>

DESCRIPTION
       The ncurses library routines give the user a terminal-independent
       method of updating character screens with reasonable 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.7.

       The ncurses library emulates the curses(3) 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.

       The ncurses package supports: overall screen, window and pad
       manipulation; output to windows and pads; reading terminal input;
       control over terminal and curses input and output options; environment
       query routines; color manipulation; use of soft label keys; terminfo
       capabilities; and access to low-level terminal-manipulation routines.

       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 initialize 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 following sequence should be
       used:

	     initscr(); cbreak(); noecho();

       Most programs would additionally use the sequence:

	     nonl();
	     intrflush(stdscr, FALSE);
	     keypad(stdscr, TRUE);

       Before a curses 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 tput init command after the shell
       environment variable TERM has been exported.  tset(1) is usually
       responsible for doing this.  [See terminfo(5) for further details.]

       The ncurses library permits manipulation of data structures, called
       windows, which can be thought of as two-dimensional arrays of
       characters representing all or part of a CRT screen.  A default window
       called stdscr, which is the size of the terminal screen, is supplied.
       Others may be created with newwin.

       Note that curses does not handle overlapping windows, that's done by
       the panel(3) library.  This means that you can either use stdscr or
       divide the screen into tiled windows 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 *.  These data
       structures are manipulated with routines described here and elsewhere
       in the ncurses manual pages.  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.

       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.  These are windows
       which are not constrained to the size of the screen and whose contents
       need not be completely displayed.  See curs_pad(3) for more
       information.

       In addition to drawing characters on the screen, video attributes and
       colors may be supported, causing the characters 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 <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 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).

       If the environment variable TERMINFO is defined, any program 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 definition is found in

	     /usr/share/misc/terminfo/a/att4424.

       (The a is copied from the first letter of att4424 to avoid creation of
       huge directories.)  However, if TERMINFO is set to $HOME/myterms,
       curses first checks

	     $HOME/myterms/a/att4424,

       and if that fails, it then checks

	     /usr/share/misc/terminfo/a/att4424.

       This is useful for developing experimental definitions or when write
       permission in /usr/share/misc/terminfo is not available.

       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 values 1 and 0, respectively.

       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 curscr can be used in only a few
       routines.

   Routine and Argument Names
       Many curses routines have two or more versions.	The routines prefixed
       with w require a window argument.  The routines prefixed with p require
       a pad argument.	Those without 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 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 specified before the
       coordinates.

       In each case, win is the window affected, and pad is the pad affected;
       win and pad are always pointers to type WINDOW.

       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 WINDOW, 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.	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 characters:
	      cchar_t
		   corresponds to chtype.  However it is a structure, because
		   more data is stored than can fit into an integer.  The
		   characters 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 separate 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 "normal" library.  There is a naming convention
	      which relates many of the normal/wide variants: 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 XPG4 or present in SVr4.

       curses Routine Name     Manual Page Name
       ===========================================
       COLOR_PAIR	       curs_color(3)
       PAIR_NUMBER	       curs_attr(3)
       _nc_free_and_exit       curs_memleaks(3)*
       _nc_freeall	       curs_memleaks(3)*
       _nc_tracebits	       curs_trace(3)*
       _traceattr	       curs_trace(3)*
       _traceattr2	       curs_trace(3)*
       _tracechar	       curs_trace(3)*
       _tracechtype	       curs_trace(3)*
       _tracechtype2	       curs_trace(3)*
       _tracedump	       curs_trace(3)*
       _tracef		       curs_trace(3)*
       _tracemouse	       curs_trace(3)*
       add_wch		       curs_add_wch(3)
       add_wchnstr	       curs_add_wchstr(3)
       add_wchstr	       curs_add_wchstr(3)
       addch		       curs_addch(3)
       addchnstr	       curs_addchstr(3)
       addchstr		       curs_addchstr(3)
       addnstr		       curs_addstr(3)
       addnwstr		       curs_addwstr(3)
       addstr		       curs_addstr(3)
       addwstr		       curs_addwstr(3)
       assume_default_colors   default_colors(3)*
       attr_get		       curs_attr(3)
       attr_off		       curs_attr(3)
       attr_on		       curs_attr(3)
       attr_set		       curs_attr(3)
       attroff		       curs_attr(3)
       attron		       curs_attr(3)
       attrset		       curs_attr(3)
       baudrate		       curs_termattrs(3)
       beep		       curs_beep(3)
       bkgd		       curs_bkgd(3)
       bkgdset		       curs_bkgd(3)
       bkgrnd		       curs_bkgrnd(3)
       bkgrndset	       curs_bkgrnd(3)
       border		       curs_border(3)
       border_set	       curs_border_set(3)
       box		       curs_border(3)
       box_set		       curs_border_set(3)
       can_change_color	       curs_color(3)
       cbreak		       curs_inopts(3)
       chgat		       curs_attr(3)
       clear		       curs_clear(3)
       clearok		       curs_outopts(3)
       clrtobot		       curs_clear(3)
       clrtoeol		       curs_clear(3)
       color_content	       curs_color(3)
       color_set	       curs_attr(3)
       copywin		       curs_overlay(3)
       curs_set		       curs_kernel(3)
       curses_version	       curs_extend(3)*
       def_prog_mode	       curs_kernel(3)
       def_shell_mode	       curs_kernel(3)
       define_key	       define_key(3)*
       del_curterm	       terminfo(3)
       delay_output	       curs_util(3)
       delch		       curs_delch(3)
       deleteln		       curs_deleteln(3)
       delscreen	       curs_initscr(3)
       delwin		       curs_window(3)
       derwin		       curs_window(3)
       doupdate		       curs_refresh(3)
       dupwin		       curs_window(3)
       echo		       curs_inopts(3)
       echo_wchar	       curs_add_wch(3)
       echochar		       curs_addch(3)
       endwin		       curs_initscr(3)
       erase		       curs_clear(3)
       erasechar	       curs_termattrs(3)
       erasewchar	       curs_termattrs(3)
       filter		       curs_util(3)
       flash		       curs_beep(3)
       flushinp		       curs_util(3)
       get_wch		       curs_get_wch(3)
       get_wstr		       curs_get_wstr(3)
       getattrs		       curs_attr(3)
       getbegx		       curs_legacy(3)*
       getbegy		       curs_legacy(3)*
       getbegyx		       curs_getyx(3)
       getbkgd		       curs_bkgd(3)
       getbkgrnd	       curs_bkgrnd(3)
       getcchar		       curs_getcchar(3)
       getch		       curs_getch(3)
       getcurx		       curs_legacy(3)*
       getcury		       curs_legacy(3)*
       getmaxx		       curs_legacy(3)*
       getmaxy		       curs_legacy(3)*
       getmaxyx		       curs_getyx(3)
       getmouse		       curs_mouse(3)*
       getn_wstr	       curs_get_wstr(3)
       getnstr		       curs_getstr(3)
       getparx		       curs_legacy(3)*
       getpary		       curs_legacy(3)*
       getparyx		       curs_getyx(3)
       getstr		       curs_getstr(3)
       getsyx		       curs_kernel(3)
       getwin		       curs_util(3)
       getyx		       curs_getyx(3)
       halfdelay	       curs_inopts(3)
       has_colors	       curs_color(3)
       has_ic		       curs_termattrs(3)
       has_il		       curs_termattrs(3)
       has_key		       curs_getch(3)*
       hline		       curs_border(3)
       hline_set	       curs_border_set(3)
       idcok		       curs_outopts(3)
       idlok		       curs_outopts(3)
       immedok		       curs_outopts(3)
       in_wch		       curs_in_wch(3)
       in_wchnstr	       curs_in_wchstr(3)
       in_wchstr	       curs_in_wchstr(3)
       inch		       curs_inch(3)
       inchnstr		       curs_inchstr(3)
       inchstr		       curs_inchstr(3)
       init_color	       curs_color(3)
       init_pair	       curs_color(3)
       initscr		       curs_initscr(3)
       innstr		       curs_instr(3)
       innwstr		       curs_inwstr(3)
       ins_nwstr	       curs_ins_wstr(3)
       ins_wch		       curs_ins_wch(3)
       ins_wstr		       curs_ins_wstr(3)
       insch		       curs_insch(3)
       insdelln		       curs_deleteln(3)
       insertln		       curs_deleteln(3)
       insnstr		       curs_insstr(3)
       insstr		       curs_insstr(3)
       instr		       curs_instr(3)
       intrflush	       curs_inopts(3)
       inwstr		       curs_inwstr(3)
       is_cleared	       curs_opaque(3)*
       is_idcok		       curs_opaque(3)*
       is_idlok		       curs_opaque(3)*
       is_immedok	       curs_opaque(3)*
       is_keypad	       curs_opaque(3)*
       is_leaveok	       curs_opaque(3)*
       is_linetouched	       curs_touch(3)
       is_nodelay	       curs_opaque(3)*
       is_notimeout	       curs_opaque(3)*
       is_scrollok	       curs_opaque(3)*
       is_syncok	       curs_opaque(3)*
       is_term_resized	       resizeterm(3)*
       is_wintouched	       curs_touch(3)
       isendwin		       curs_initscr(3)
       key_defined	       key_defined(3)*
       key_name		       curs_util(3)
       keybound		       keybound(3)*
       keyname		       curs_util(3)
       keyok		       keyok(3)*
       keypad		       curs_inopts(3)
       killchar		       curs_termattrs(3)
       killwchar	       curs_termattrs(3)
       leaveok		       curs_outopts(3)
       longname		       curs_termattrs(3)
       mcprint		       curs_print(3)*
       meta		       curs_inopts(3)
       mouse_trafo	       curs_mouse(3)*
       mouseinterval	       curs_mouse(3)*
       mousemask	       curs_mouse(3)*
       move		       curs_move(3)
       mvadd_wch	       curs_add_wch(3)
       mvadd_wchnstr	       curs_add_wchstr(3)
       mvadd_wchstr	       curs_add_wchstr(3)
       mvaddch		       curs_addch(3)
       mvaddchnstr	       curs_addchstr(3)
       mvaddchstr	       curs_addchstr(3)
       mvaddnstr	       curs_addstr(3)
       mvaddnwstr	       curs_addwstr(3)
       mvaddstr		       curs_addstr(3)
       mvaddwstr	       curs_addwstr(3)
       mvchgat		       curs_attr(3)
       mvcur		       terminfo(3)
       mvdelch		       curs_delch(3)
       mvderwin		       curs_window(3)
       mvget_wch	       curs_get_wch(3)
       mvget_wstr	       curs_get_wstr(3)
       mvgetch		       curs_getch(3)
       mvgetn_wstr	       curs_get_wstr(3)
       mvgetnstr	       curs_getstr(3)
       mvgetstr		       curs_getstr(3)
       mvhline		       curs_border(3)
       mvhline_set	       curs_border_set(3)
       mvin_wch		       curs_in_wch(3)
       mvin_wchnstr	       curs_in_wchstr(3)
       mvin_wchstr	       curs_in_wchstr(3)
       mvinch		       curs_inch(3)
       mvinchnstr	       curs_inchstr(3)
       mvinchstr	       curs_inchstr(3)
       mvinnstr		       curs_instr(3)
       mvinnwstr	       curs_inwstr(3)
       mvins_nwstr	       curs_ins_wstr(3)
       mvins_wch	       curs_ins_wch(3)
       mvins_wstr	       curs_ins_wstr(3)
       mvinsch		       curs_insch(3)
       mvinsnstr	       curs_insstr(3)
       mvinsstr		       curs_insstr(3)
       mvinstr		       curs_instr(3)
       mvinwstr		       curs_inwstr(3)
       mvprintw		       curs_printw(3)
       mvscanw		       curs_scanw(3)
       mvvline		       curs_border(3)
       mvvline_set	       curs_border_set(3)
       mvwadd_wch	       curs_add_wch(3)
       mvwadd_wchnstr	       curs_add_wchstr(3)
       mvwadd_wchstr	       curs_add_wchstr(3)
       mvwaddch		       curs_addch(3)
       mvwaddchnstr	       curs_addchstr(3)
       mvwaddchstr	       curs_addchstr(3)
       mvwaddnstr	       curs_addstr(3)
       mvwaddnwstr	       curs_addwstr(3)
       mvwaddstr	       curs_addstr(3)
       mvwaddwstr	       curs_addwstr(3)
       mvwchgat		       curs_attr(3)
       mvwdelch		       curs_delch(3)
       mvwget_wch	       curs_get_wch(3)
       mvwget_wstr	       curs_get_wstr(3)
       mvwgetch		       curs_getch(3)
       mvwgetn_wstr	       curs_get_wstr(3)
       mvwgetnstr	       curs_getstr(3)
       mvwgetstr	       curs_getstr(3)
       mvwhline		       curs_border(3)
       mvwhline_set	       curs_border_set(3)
       mvwin		       curs_window(3)
       mvwin_wch	       curs_in_wch(3)
       mvwin_wchnstr	       curs_in_wchstr(3)
       mvwin_wchstr	       curs_in_wchstr(3)
       mvwinch		       curs_inch(3)
       mvwinchnstr	       curs_inchstr(3)
       mvwinchstr	       curs_inchstr(3)
       mvwinnstr	       curs_instr(3)
       mvwinnwstr	       curs_inwstr(3)
       mvwins_nwstr	       curs_ins_wstr(3)
       mvwins_wch	       curs_ins_wch(3)
       mvwins_wstr	       curs_ins_wstr(3)
       mvwinsch		       curs_insch(3)
       mvwinsnstr	       curs_insstr(3)
       mvwinsstr	       curs_insstr(3)
       mvwinstr		       curs_instr(3)
       mvwinwstr	       curs_inwstr(3)
       mvwprintw	       curs_printw(3)
       mvwscanw		       curs_scanw(3)
       mvwvline		       curs_border(3)
       mvwvline_set	       curs_border_set(3)
       napms		       curs_kernel(3)
       newpad		       curs_pad(3)
       newterm		       curs_initscr(3)
       newwin		       curs_window(3)
       nl		       curs_outopts(3)
       nocbreak		       curs_inopts(3)
       nodelay		       curs_inopts(3)
       noecho		       curs_inopts(3)
       nofilter		       curs_util(3)*
       nonl		       curs_outopts(3)
       noqiflush	       curs_inopts(3)
       noraw		       curs_inopts(3)
       notimeout	       curs_inopts(3)
       overlay		       curs_overlay(3)
       overwrite	       curs_overlay(3)
       pair_content	       curs_color(3)
       pechochar	       curs_pad(3)
       pnoutrefresh	       curs_pad(3)
       prefresh		       curs_pad(3)
       printw		       curs_printw(3)
       putp		       terminfo(3)
       putwin		       curs_util(3)
       qiflush		       curs_inopts(3)
       raw		       curs_inopts(3)
       redrawwin	       curs_refresh(3)
       refresh		       curs_refresh(3)
       reset_prog_mode	       curs_kernel(3)
       reset_shell_mode	       curs_kernel(3)
       resetty		       curs_kernel(3)
       resizeterm	       resizeterm(3)*
       restartterm	       terminfo(3)
       ripoffline	       curs_kernel(3)
       savetty		       curs_kernel(3)
       scanw		       curs_scanw(3)
       scr_dump		       curs_scr_dump(3)
       scr_init		       curs_scr_dump(3)
       scr_restore	       curs_scr_dump(3)
       scr_set		       curs_scr_dump(3)
       scrl		       curs_scroll(3)
       scroll		       curs_scroll(3)
       scrollok		       curs_outopts(3)
       set_curterm	       terminfo(3)
       set_term		       curs_initscr(3)
       setcchar		       curs_getcchar(3)
       setscrreg	       curs_outopts(3)
       setsyx		       curs_kernel(3)
       setterm		       terminfo(3)
       setupterm	       terminfo(3)
       slk_attr		       curs_slk(3)*
       slk_attr_off	       curs_slk(3)
       slk_attr_on	       curs_slk(3)
       slk_attr_set	       curs_slk(3)
       slk_attroff	       curs_slk(3)
       slk_attron	       curs_slk(3)
       slk_attrset	       curs_slk(3)
       slk_clear	       curs_slk(3)
       slk_color	       curs_slk(3)
       slk_init		       curs_slk(3)
       slk_label	       curs_slk(3)
       slk_noutrefresh	       curs_slk(3)
       slk_refresh	       curs_slk(3)
       slk_restore	       curs_slk(3)
       slk_set		       curs_slk(3)
       slk_touch	       curs_slk(3)
       standend		       curs_attr(3)
       standout		       curs_attr(3)
       start_color	       curs_color(3)
       subpad		       curs_pad(3)
       subwin		       curs_window(3)
       syncok		       curs_window(3)
       term_attrs	       curs_termattrs(3)
       termattrs	       curs_termattrs(3)
       termname		       curs_termattrs(3)
       tgetent		       termcap(3)
       tgetflag		       termcap(3)
       tgetnum		       termcap(3)
       tgetstr		       termcap(3)
       tgoto		       termcap(3)
       tigetflag	       terminfo(3)
       tigetnum		       terminfo(3)
       tigetstr		       terminfo(3)
       timeout		       curs_inopts(3)
       touchline	       curs_touch(3)
       touchwin		       curs_touch(3)
       tparm		       terminfo(3)
       tputs		       termcap(3)
       tputs		       terminfo(3)
       trace		       curs_trace(3)*
       typeahead	       curs_inopts(3)
       unctrl		       curs_util(3)
       unget_wch	       curs_get_wch(3)
       ungetch		       curs_getch(3)
       ungetmouse	       curs_mouse(3)*
       untouchwin	       curs_touch(3)
       use_default_colors      default_colors(3)*
       use_env		       curs_util(3)
       use_extended_names      curs_extend(3)*
       use_legacy_coding       legacy_coding(3)*
       vid_attr		       terminfo(3)
       vid_puts		       terminfo(3)
       vidattr		       terminfo(3)
       vidputs		       terminfo(3)
       vline		       curs_border(3)
       vline_set	       curs_border_set(3)
       vw_printw	       curs_printw(3)
       vw_scanw		       curs_scanw(3)
       vwprintw		       curs_printw(3)
       vwscanw		       curs_scanw(3)
       wadd_wch		       curs_add_wch(3)
       wadd_wchnstr	       curs_add_wchstr(3)
       wadd_wchstr	       curs_add_wchstr(3)
       waddch		       curs_addch(3)
       waddchnstr	       curs_addchstr(3)
       waddchstr	       curs_addchstr(3)
       waddnstr		       curs_addstr(3)
       waddnwstr	       curs_addwstr(3)
       waddstr		       curs_addstr(3)
       waddwstr		       curs_addwstr(3)
       wattr_get	       curs_attr(3)
       wattr_off	       curs_attr(3)
       wattr_on		       curs_attr(3)
       wattr_set	       curs_attr(3)
       wattroff		       curs_attr(3)
       wattron		       curs_attr(3)
       wattrset		       curs_attr(3)
       wbkgd		       curs_bkgd(3)
       wbkgdset		       curs_bkgd(3)
       wbkgrnd		       curs_bkgrnd(3)
       wbkgrndset	       curs_bkgrnd(3)
       wborder		       curs_border(3)
       wborder_set	       curs_border_set(3)
       wchgat		       curs_attr(3)
       wclear		       curs_clear(3)
       wclrtobot	       curs_clear(3)
       wclrtoeol	       curs_clear(3)
       wcolor_set	       curs_attr(3)
       wcursyncup	       curs_window(3)
       wdelch		       curs_delch(3)
       wdeleteln	       curs_deleteln(3)
       wecho_wchar	       curs_add_wch(3)
       wechochar	       curs_addch(3)
       wenclose		       curs_mouse(3)*
       werase		       curs_clear(3)
       wget_wch		       curs_get_wch(3)
       wget_wstr	       curs_get_wstr(3)
       wgetbkgrnd	       curs_bkgrnd(3)
       wgetch		       curs_getch(3)
       wgetn_wstr	       curs_get_wstr(3)
       wgetnstr		       curs_getstr(3)
       wgetstr		       curs_getstr(3)
       whline		       curs_border(3)
       whline_set	       curs_border_set(3)
       win_wch		       curs_in_wch(3)
       win_wchnstr	       curs_in_wchstr(3)
       win_wchstr	       curs_in_wchstr(3)
       winch		       curs_inch(3)
       winchnstr	       curs_inchstr(3)
       winchstr		       curs_inchstr(3)
       winnstr		       curs_instr(3)
       winnwstr		       curs_inwstr(3)
       wins_nwstr	       curs_ins_wstr(3)
       wins_wch		       curs_ins_wch(3)
       wins_wstr	       curs_ins_wstr(3)
       winsch		       curs_insch(3)
       winsdelln	       curs_deleteln(3)
       winsertln	       curs_deleteln(3)
       winsnstr		       curs_insstr(3)
       winsstr		       curs_insstr(3)
       winstr		       curs_instr(3)
       winwstr		       curs_inwstr(3)
       wmouse_trafo	       curs_mouse(3)*
       wmove		       curs_move(3)
       wnoutrefresh	       curs_refresh(3)
       wprintw		       curs_printw(3)
       wredrawln	       curs_refresh(3)
       wrefresh		       curs_refresh(3)
       wresize		       wresize(3)*
       wscanw		       curs_scanw(3)
       wscrl		       curs_scroll(3)
       wsetscrreg	       curs_outopts(3)
       wstandend	       curs_attr(3)
       wstandout	       curs_attr(3)
       wsyncdown	       curs_window(3)
       wsyncup		       curs_window(3)
       wtimeout		       curs_inopts(3)
       wtouchln		       curs_touch(3)
       wunctrl		       curs_util(3)
       wvline		       curs_border(3)
       wvline_set	       curs_border_set(3)

RETURN VALUE
       Routines that return an integer return ERR upon failure and an integer
       value other than ERR upon successful completion, unless otherwise noted
       in the routine descriptions.

       All macros return the value of the w version, except setscrreg,
       wsetscrreg, getyx, getbegyx, and getmaxyx.  The 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).

       Routines that return pointers return NULL on error.

ENVIRONMENT
       The following environment symbols are useful for customizing the
       runtime behavior of the ncurses library.	 The most 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.

       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 terminfo entries provide this feature.

       COLUMNS
	    Specify the width of the screen in characters.  Applications
	    running in a windowing environment usually are able to obtain the
	    width of the window in which they are executing.  If neither the
	    COLUMNS value nor the terminal's screen size is available, ncurses
	    uses the size which may be specified in the terminfo database
	    (i.e., the cols capability).

	    It is important that your application use a correct size for the
	    screen.  This is not always possible because your application may
	    be running on a host which does not honor NAWS (Negotiations About
	    Window Size), or because you are temporarily running as another
	    user.  However, setting COLUMNS and/or LINES overrides the
	    library's use of the screen size obtained from the operating
	    system.

	    Either COLUMNS or LINES symbols may be specified independently.
	    This is mainly useful to circumvent legacy misfeatures of terminal
	    descriptions, e.g., xterm which commonly specifies a 65 line
	    screen.  For best results, lines and cols should not be specified
	    in a terminal description for terminals which are run as
	    emulations.

	    Use the use_env function to disable all use of external
	    environment (including system calls) to determine the screen size.

       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, is enough for most uses.	However, it is
	    made a variable 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.
	    The library will still see a timeout.

	    Note that xterm mouse events are built up from character 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
	    well as the individual clicks.

	    In addition to the environment variable, this implementation
	    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
	    application.

       HOME Tells ncurses where your home directory is.	 That is where it may
	    read and write auxiliary terminal descriptions:

	    $HOME/.termcap
	    $HOME/.terminfo

       LINES
	    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 the order of
	    buttons on the mouse.  OS/2 numbers a 3-button mouse
	    inconsistently from other platforms:

	    1 = left
	    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.

       NCURSES_ASSUMED_COLORS
	    Override the compiled-in assumption that the terminal's default
	    colors are white-on-black (see default_colors(3)).	You may set
	    the foreground and background color values with this environment
	    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_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 environment 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 optimization.
	    In some cases, your terminal driver may not handle these properly.
	    Set this environment variable to disable the feature.  You can
	    also adjust your stty settings to avoid the problem.

       NCURSES_NO_MAGIC_COOKIES
	    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.

       NCURSES_NO_PADDING
	    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 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
	    interfaced 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 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.

       NCURSES_NO_SETBUF
	    Normally ncurses enables buffered output during terminal
	    initialization.  This is done (as in SVr4 curses) for performance
	    reasons.  For testing purposes, 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.

       NCURSES_NO_UTF8_ACS
	    During initialization, the ncurses library checks for special
	    cases where VT100 line-drawing (and the corresponding alternate
	    character set capabilities) described in the terminfo are known to
	    be missing.	 Specifically, when running in a UTF-8 locale, the
	    Linux console emulator and the GNU screen program ignore these.
	    Ncurses checks the TERM environment variable for these.  For other
	    special cases, you should set this environment variable.  Doing
	    this tells ncurses to use Unicode values which correspond to the
	    VT100 line-drawing glyphs.	That works for the special cases
	    cited, 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.

       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.

	    The argument values, which are defined in curses.h, provide
	    several types of information.  When running with traces enabled,
	    your application will write the file trace to the current
	    directory.

       TERM Denotes your terminal type.	 Each terminal type is distinct,
	    though many are similar.

       TERMCAP
	    If the ncurses library has been configured with termcap support,
	    ncurses will check for a terminal's 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.

       TERMINFO
	    Overrides the directory in which ncurses searches for your
	    terminal description.  This is the simplest, but not the only way
	    to change the list of directories.	The complete list of
	    directories in order follows:
	    -  the last directory to which ncurses wrote, if any, is searched
	       first

	    -  the directory specified by the TERMINFO symbol

	    -  $HOME/.terminfo

	    -  directories listed in the TERMINFO_DIRS symbol

	    -  one or more directories whose names are configured and compiled
	       into the ncurses library, e.g., /usr/share/misc/terminfo

       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.

       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.

       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.

FILES
       /usr/share/tabset
	    directory containing initialization files for the terminal
	    capability database /usr/share/misc/terminfo terminal capability
	    database

SEE ALSO
       terminfo(5) and related pages whose names begin "curs_" for detailed
       routine descriptions.

       /usr/share/doc/html/curses/ncurses-intro.html
	      intro to ncurses.

       /usr/share/doc/html/curses/hackguide.html
	      ncurses hacker's guide.

EXTENSIONS
       The ncurses library can be compiled with an option (-DUSE_GETCAP) that
       falls back to the old-style /etc/termcap file if the terminal setup
       code cannot find a terminfo entry corresponding to TERM.	 Use of this
       feature is not recommended, as it essentially includes an entire
       termcap compiler in the ncurses startup code, at significant cost in
       core and startup cycles.

       The ncurses library includes facilities for capturing mouse events on
       certain terminals (including xterm).  See the curs_mouse(3) manual page
       for details.

       The ncurses library includes facilities for responding to window
       resizing events, e.g., when running in an xterm.	 See the resizeterm(3)
       and wresize(3) manual pages for details.	 In addition, the library may
       be configured with a SIGWINCH handler.

       The ncurses library extends the fixed set of function key capabilities
       of terminals by allowing the application designer to define additional
       key sequences at runtime.  See the define_key(3) key_defined(3), and
       keyok(3) manual pages for details.

       The ncurses library can exploit the capabilities of terminals which
       implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an
       application to reset the terminal to its original foreground and
       background colors.  From the users' perspective, the application is
       able to draw colored text on a background whose color is set
       independently, providing better control over color contrasts.  See the
       default_colors(3) manual page for details.

       The ncurses library includes a function for directing application
       output to a printer attached to the terminal device.  See the
       curs_print(3) manual page for details.

PORTABILITY
       The ncurses library is intended to be BASE-level conformant with XSI
       Curses.	The EXTENDED XSI Curses functionality (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 pages.

       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(3) manual page for details.

	    The routine slk_attr is not part of XPG4, nor is it present in
	    SVr4.  See the curs_slk(3) manual page for details.

	    The routines getmouse, mousemask, ungetmouse, mouseinterval, and
	    wenclose relating to mouse interfacing are not part of XPG4, nor
	    are they present in SVr4.  See the curs_mouse(3) manual page for
	    details.

	    The routine mcprint was not present in any previous curses
	    implementation.  See the curs_print(3) manual page for details.

	    The routine wresize is not part of XPG4, nor is it present in
	    SVr4.  See the wresize(3) manual page for details.

	    The WINDOW structure's internal details can be hidden from
	    application programs.  See curs_opaque(3) for the discussion of
	    is_scrollok, etc.

       In historic curses versions, delays embedded in the capabilities cr,
       ind, cub1, ff and tab activated corresponding delay bits in the UNIX
       tty driver.  In this implementation, all padding is done by sending NUL
       bytes.  This method is slightly more expensive, but narrows the
       interface to the UNIX kernel significantly and increases the package's
       portability correspondingly.

NOTES
       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 directed to standard error.
       This was an undocumented feature of AT&T System V Release 3 curses.

AUTHORS
       Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.  Based on pcurses
       by Pavel Curtis.

								 March 1, 2011
[top]

List of man pages available for OpenBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net