Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
ncurses(3X)					      ncurses(3X)

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 rea­
       sonable	 optimization.	  This	implementation	is  ``new
       curses'' (ncurses) and is  the  approved  replacement  for
       4.4BSD classic curses, which has been discontinued.

       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 BUGS sections below and
       described in detail in the EXTENSIONS and BUGS sections of
       individual man pages.

       A  program  using  these  routines must be linked with the
       -lncurses option, or (if it has been generated)	with  the
       debugging  library  -lncurses_g.   (Your system integrator
       may also have installed these libraries	under  the  names
       -lcurses and -lcurses_g.)  The ncurses_g library generates
       trace logs (in a file called 'trace' in the current direc­
       tory) that describe curses actions.

       The  ncurses  package supports: overall screen, window and
       pad manipulation; output to windows and pads; reading ter­
       minal  input;  control  over terminal and curses input and
       output options; environment query routines; color  manipu­
       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:

	     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  ter­
       minal  should  be  set  and its initialization strings, if

								1

ncurses(3X)					      ncurses(3X)

       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 struc­
       tures, 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(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
       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  which  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  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
       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 effect a program
       running in an AT&T 630 layer, for example, where the  size

								2

ncurses(3X)					      ncurses(3X)

       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
       TERM is set to att4424, then the compiled terminal defini­
       tion is found in

	     @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

	     @TERMINFO@/a/att4424.

       This  is useful for developing experimental definitions or
       when write permission in @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 val­
       ues 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  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
       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 WIN­
       DOW.

								3

ncurses(3X)					      ncurses(3X)

       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.

   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(3X)
	      PAIR_NUMBER	      curs_attr(3X)
	      _nc_tracebits	      curs_trace(3X)*
	      _traceattr	      curs_trace(3X)*
	      _traceattr2	      curs_trace(3X)*
	      _tracechar	      curs_trace(3X)*
	      _tracechtype	      curs_trace(3X)*
	      _tracechtype2	      curs_trace(3X)*
	      _tracedump	      curs_trace(3X)*
	      _tracef		      curs_trace(3X)*
	      _tracemouse	      curs_trace(3X)*
	      addch		      curs_addch(3X)
	      addchnstr 	      curs_addchstr(3X)
	      addchstr		      curs_addchstr(3X)
	      addnstr		      curs_addstr(3X)
	      addstr		      curs_addstr(3X)
	      assume_default_colors   default_colors(3X)*
	      attr_get		      curs_attr(3X)
	      attr_off		      curs_attr(3X)
	      attr_on		      curs_attr(3X)
	      attr_set		      curs_attr(3X)
	      attroff		      curs_attr(3X)
	      attron		      curs_attr(3X)
	      attrset		      curs_attr(3X)
	      baudrate		      curs_termattrs(3X)
	      beep		      curs_beep(3X)
	      bkgd		      curs_bkgd(3X)
	      bkgdset		      curs_bkgd(3X)
	      border		      curs_border(3X)
	      box		      curs_border(3X)
	      can_change_color	      curs_color(3X)
	      cbreak		      curs_inopts(3X)
	      chgat		      curs_attr(3X)
	      clear		      curs_clear(3X)
	      clearok		      curs_outopts(3X)
	      clrtobot		      curs_clear(3X)
	      clrtoeol		      curs_clear(3X)

								4

ncurses(3X)					      ncurses(3X)

	      color_content	      curs_color(3X)
	      color_set 	      curs_attr(3X)
	      copywin		      curs_overlay(3X)
	      curs_set		      curs_kernel(3X)
	      curses_version	      curs_extend(3X)*
	      def_prog_mode	      curs_kernel(3X)
	      def_shell_mode	      curs_kernel(3X)
	      define_key	      define_key(3X)*
	      del_curterm	      curs_terminfo(3X)
	      delay_output	      curs_util(3X)
	      delch		      curs_delch(3X)
	      deleteln		      curs_deleteln(3X)
	      delscreen 	      curs_initscr(3X)
	      delwin		      curs_window(3X)
	      derwin		      curs_window(3X)
	      doupdate		      curs_refresh(3X)
	      dupwin		      curs_window(3X)
	      echo		      curs_inopts(3X)
	      echochar		      curs_addch(3X)
	      endwin		      curs_initscr(3X)
	      erase		      curs_clear(3X)
	      erasechar 	      curs_termattrs(3X)
	      filter		      curs_util(3X)
	      flash		      curs_beep(3X)
	      flushinp		      curs_util(3X)
	      getbegyx		      curs_getyx(3X)
	      getbkgd		      curs_bkgd(3X)
	      getch		      curs_getch(3X)
	      getmaxyx		      curs_getyx(3X)
	      getmouse		      curs_mouse(3X)*
	      getnstr		      curs_getstr(3X)
	      getparyx		      curs_getyx(3X)
	      getstr		      curs_getstr(3X)
	      getsyx		      curs_kernel(3X)
	      getwin		      curs_util(3X)
	      getyx		      curs_getyx(3X)
	      halfdelay 	      curs_inopts(3X)
	      has_colors	      curs_color(3X)
	      has_ic		      curs_termattrs(3X)
	      has_il		      curs_termattrs(3X)
	      has_key		      curs_getch(3X)*
	      hline		      curs_border(3X)
	      idcok		      curs_outopts(3X)
	      idlok		      curs_outopts(3X)
	      immedok		      curs_outopts(3X)
	      inch		      curs_inch(3X)
	      inchnstr		      curs_inchstr(3X)
	      inchstr		      curs_inchstr(3X)
	      init_color	      curs_color(3X)
	      init_pair 	      curs_color(3X)
	      initscr		      curs_initscr(3X)
	      innstr		      curs_instr(3X)
	      insch		      curs_insch(3X)

								5

ncurses(3X)					      ncurses(3X)

	      insdelln		      curs_deleteln(3X)
	      insertln		      curs_deleteln(3X)
	      insnstr		      curs_insstr(3X)
	      insstr		      curs_insstr(3X)
	      instr		      curs_instr(3X)
	      intrflush 	      curs_inopts(3X)
	      is_linetouched	      curs_touch(3X)
	      is_wintouched	      curs_touch(3X)
	      isendwin		      curs_initscr(3X)
	      keybound		      keybound(3X)*
	      keyname		      curs_util(3X)
	      keyok		      keyok(3X)*
	      keypad		      curs_inopts(3X)
	      killchar		      curs_termattrs(3X)
	      leaveok		      curs_outopts(3X)
	      longname		      curs_termattrs(3X)
	      mcprint		      curs_print(3X)*
	      meta		      curs_inopts(3X)
	      mouse_trafo	      curs_mouse(3X)*
	      mouseinterval	      curs_mouse(3X)*
	      mousemask 	      curs_mouse(3X)*
	      move		      curs_move(3X)
	      mvaddch		      curs_addch(3X)
	      mvaddchnstr	      curs_addchstr(3X)
	      mvaddchstr	      curs_addchstr(3X)
	      mvaddnstr 	      curs_addstr(3X)
	      mvaddstr		      curs_addstr(3X)
	      mvchgat		      curs_attr(3X)
	      mvcur		      curs_terminfo(3X)
	      mvdelch		      curs_delch(3X)
	      mvderwin		      curs_window(3X)
	      mvgetch		      curs_getch(3X)
	      mvgetnstr 	      curs_getstr(3X)
	      mvgetstr		      curs_getstr(3X)
	      mvhline		      curs_border(3X)
	      mvinch		      curs_inch(3X)
	      mvinchnstr	      curs_inchstr(3X)
	      mvinchstr 	      curs_inchstr(3X)
	      mvinnstr		      curs_instr(3X)
	      mvinsch		      curs_insch(3X)
	      mvinsnstr 	      curs_insstr(3X)
	      mvinsstr		      curs_insstr(3X)
	      mvinstr		      curs_instr(3X)
	      mvprintw		      curs_printw(3X)
	      mvscanw		      curs_scanw(3X)
	      mvvline		      curs_border(3X)
	      mvwaddch		      curs_addch(3X)
	      mvwaddchnstr	      curs_addchstr(3X)
	      mvwaddchstr	      curs_addchstr(3X)
	      mvwaddnstr	      curs_addstr(3X)
	      mvwaddstr 	      curs_addstr(3X)
	      mvwchgat		      curs_attr(3X)
	      mvwdelch		      curs_delch(3X)

								6

ncurses(3X)					      ncurses(3X)

	      mvwgetch		      curs_getch(3X)
	      mvwgetnstr	      curs_getstr(3X)
	      mvwgetstr 	      curs_getstr(3X)
	      mvwhline		      curs_border(3X)
	      mvwin		      curs_window(3X)
	      mvwinch		      curs_inch(3X)
	      mvwinchnstr	      curs_inchstr(3X)
	      mvwinchstr	      curs_inchstr(3X)
	      mvwinnstr 	      curs_instr(3X)
	      mvwinsch		      curs_insch(3X)
	      mvwinsnstr	      curs_insstr(3X)
	      mvwinsstr 	      curs_insstr(3X)
	      mvwinstr		      curs_instr(3X)
	      mvwprintw 	      curs_printw(3X)
	      mvwscanw		      curs_scanw(3X)
	      mvwvline		      curs_border(3X)
	      napms		      curs_kernel(3X)
	      newpad		      curs_pad(3X)
	      newterm		      curs_initscr(3X)
	      newwin		      curs_window(3X)
	      nl		      curs_outopts(3X)
	      nocbreak		      curs_inopts(3X)
	      nodelay		      curs_inopts(3X)
	      noecho		      curs_inopts(3X)
	      nonl		      curs_outopts(3X)
	      noqiflush 	      curs_inopts(3X)
	      noraw		      curs_inopts(3X)
	      notimeout 	      curs_inopts(3X)
	      overlay		      curs_overlay(3X)
	      overwrite 	      curs_overlay(3X)
	      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)
	      raw		      curs_inopts(3X)
	      redrawwin 	      curs_refresh(3X)
	      refresh		      curs_refresh(3X)
	      reset_prog_mode	      curs_kernel(3X)
	      reset_shell_mode	      curs_kernel(3X)
	      resetty		      curs_kernel(3X)
	      resizeterm	      resizeterm(3X)*
	      restartterm	      curs_terminfo(3X)
	      ripoffline	      curs_kernel(3X)
	      savetty		      curs_kernel(3X)
	      scanw		      curs_scanw(3X)
	      scr_dump		      curs_scr_dump(3X)
	      scr_init		      curs_scr_dump(3X)
	      scr_restore	      curs_scr_dump(3X)
	      scr_set		      curs_scr_dump(3X)

								7

ncurses(3X)					      ncurses(3X)

	      scrl		      curs_scroll(3X)
	      scroll		      curs_scroll(3X)
	      scrollok		      curs_outopts(3X)
	      set_curterm	      curs_terminfo(3X)
	      set_term		      curs_initscr(3X)
	      setscrreg 	      curs_outopts(3X)
	      setsyx		      curs_kernel(3X)
	      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)
	      slk_attroff	      curs_slk(3X)
	      slk_attron	      curs_slk(3X)
	      slk_attrset	      curs_slk(3X)
	      slk_clear 	      curs_slk(3X)
	      slk_color 	      curs_slk(3X)
	      slk_init		      curs_slk(3X)
	      slk_label 	      curs_slk(3X)
	      slk_noutrefresh	      curs_slk(3X)
	      slk_refresh	      curs_slk(3X)
	      slk_restore	      curs_slk(3X)
	      slk_set		      curs_slk(3X)
	      slk_touch 	      curs_slk(3X)
	      standend		      curs_attr(3X)
	      standout		      curs_attr(3X)
	      start_color	      curs_color(3X)
	      subpad		      curs_pad(3X)
	      subwin		      curs_window(3X)
	      syncok		      curs_window(3X)
	      termattrs 	      curs_termattrs(3X)
	      termname		      curs_termattrs(3X)
	      tgetent		      curs_termcap(3X)
	      tgetflag		      curs_termcap(3X)
	      tgetnum		      curs_termcap(3X)
	      tgetstr		      curs_termcap(3X)
	      tgoto		      curs_termcap(3X)
	      tigetflag 	      curs_terminfo(3X)
	      tigetnum		      curs_terminfo(3X)
	      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)*
	      typeahead 	      curs_inopts(3X)
	      unctrl		      curs_util(3X)
	      ungetch		      curs_getch(3X)
	      ungetmouse	      curs_mouse(3X)*
	      untouchwin	      curs_touch(3X)

								8

ncurses(3X)					      ncurses(3X)

	      use_default_colors      default_colors(3X)*
	      use_env		      curs_util(3X)
	      use_extended_names      curs_extend(3X)*
	      vidattr		      curs_terminfo(3X)
	      vidputs		      curs_terminfo(3X)
	      vline		      curs_border(3X)
	      vw_printw 	      curs_printw(3X)
	      vw_scanw		      curs_scanw(3X)
	      vwprintw		      curs_printw(3X)
	      vwscanw		      curs_scanw(3X)
	      waddch		      curs_addch(3X)
	      waddchnstr	      curs_addchstr(3X)
	      waddchstr 	      curs_addchstr(3X)
	      waddnstr		      curs_addstr(3X)
	      waddstr		      curs_addstr(3X)
	      wattr_get 	      curs_attr(3X)
	      wattr_off 	      curs_attr(3X)
	      wattr_on		      curs_attr(3X)
	      wattr_set 	      curs_attr(3X)
	      wattroff		      curs_attr(3X)
	      wattron		      curs_attr(3X)
	      wattrset		      curs_attr(3X)
	      wbkgd		      curs_bkgd(3X)
	      wbkgdset		      curs_bkgd(3X)
	      wborder		      curs_border(3X)
	      wchgat		      curs_attr(3X)
	      wclear		      curs_clear(3X)
	      wclrtobot 	      curs_clear(3X)
	      wclrtoeol 	      curs_clear(3X)
	      wcolor_set	      curs_attr(3X)
	      wcursyncup	      curs_window(3X)
	      wdelch		      curs_delch(3X)
	      wdeleteln 	      curs_deleteln(3X)
	      wechochar 	      curs_addch(3X)
	      wenclose		      curs_mouse(3X)*
	      werase		      curs_clear(3X)
	      wgetch		      curs_getch(3X)
	      wgetnstr		      curs_getstr(3X)
	      wgetstr		      curs_getstr(3X)
	      whline		      curs_border(3X)
	      winch		      curs_inch(3X)
	      winchnstr 	      curs_inchstr(3X)
	      winchstr		      curs_inchstr(3X)
	      winnstr		      curs_instr(3X)
	      winsch		      curs_insch(3X)
	      winsdelln 	      curs_deleteln(3X)
	      winsertln 	      curs_deleteln(3X)
	      winsnstr		      curs_insstr(3X)
	      winsstr		      curs_insstr(3X)
	      winstr		      curs_instr(3X)
	      wmouse_trafo	      curs_mouse(3X)*
	      wmove		      curs_move(3X)
	      wnoutrefresh	      curs_refresh(3X)

								9

ncurses(3X)					      ncurses(3X)

	      wprintw		      curs_printw(3X)
	      wredrawln 	      curs_refresh(3X)
	      wrefresh		      curs_refresh(3X)
	      wresize		      wresize(3X)*
	      wscanw		      curs_scanw(3X)
	      wscrl		      curs_scroll(3X)
	      wsetscrreg	      curs_outopts(3X)
	      wstandend 	      curs_attr(3X)
	      wstandout 	      curs_attr(3X)
	      wsyncdown 	      curs_window(3X)
	      wsyncup		      curs_window(3X)
	      wtimeout		      curs_inopts(3X)
	      wtouchln		      curs_touch(3X)
	      wvline		      curs_border(3X)

RETURN VALUE
       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.

       All  macros  return  the  value	of  the w version, except
       setscrreg, wsetscrreg,  getyx,  getbegyx,  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 customiz­
       ing 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  ter­
	    minfo entries provide this feature.

       COLUMNS
	    Specify  the  width  of  the  screen  in  characters.
	    Applications running in a windowing environment  usu­
	    ally  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

							       10

ncurses(3X)					      ncurses(3X)

	    terminfo database (i.e., the cols capability).

	    It	is  important that your application use a correct
	    size for the screen.  However,  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.

	    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 this feature.

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

       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

							       11

ncurses(3X)					      ncurses(3X)

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

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

       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.

							       12

ncurses(3X)					      ncurses(3X)

	    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 term­
	    cap 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., @TER­
	       MINFO@

       TERMINFO_DIRS
	    Specifies  a list of directories to search for termi­
	    nal descriptions.  The list is  separated  by  colons
	    (i.e., ":").  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  file­
	    names  separated  by  colons  (i.e.,  ":").   If  the
	    TERMPATH symbol is not  set,  ncurses  looks  in  the
	    files   /etc/termcap,   /usr/share/misc/termcap   and
	    $HOME/.termcap, in that order.

							       13

ncurses(3X)					      ncurses(3X)

       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/misc/terminfo/tabset
	    directory  containing  initialization  files  for the
	    terminal  capability  database  @TERMINFO@	 terminal
	    capability database

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

EXTENSIONS
       The  ncurses  library  can  be  compiled  with  an  option
       (-DUSE_GETCAP) that falls back to the old-style /etc/term­
       cap 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(3X) 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(3X) and wresize(3X)  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(3X)  and  keyok(3X)  manual pages for
       details.

       The ncurses library can exploit the capabilities of termi­
       nals  which  implement the ISO-6429 SGR 39 and SGR 49 con­
       trols, 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  col­
       ored  text  on  a  background  whose color is set indepen­
       dently, providing better  control  over	color  contrasts.
       See the use_default_colors(3X) 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(3X) manual page for details.

							       14

ncurses(3X)					      ncurses(3X)

PORTABILITY
       The  ncurses  library is intended to be BASE-level confor­
       mant with the XSI Curses standard.   Certain  portions  of
       the  EXTENDED  XSI  Curses  functionality (including color
       support) are supported.	The following EXTENDED XSI Curses
       calls  in  support  of wide (multibyte) characters are not
       yet implemented: add_wch, add_wchnstr, add_wchstr,  addnw­
       str,  addwstr,  bkgrnd,	bkgrndset,  border_set,  box_set,
       echo_wchar,  erasewchar,  get_wch,  get_wstr,   getbkgrnd,
       getcchar,   getn_wstr,	getwchtype,   hline_set,  in_wch,
       in_wchnstr,  in_wchstr,	 innwstr,   ins_nwstr,	 ins_wch,
       ins_wstr,  inwchnstr,  inwchstr,  inwstr,  key_name, kill­
       wchar, mvadd_wch, mvadd_wchnstr, mvadd_wchstr, mvaddnwstr,
       mvaddwstr,   mvget_wch,	 mvget_wstr,   mvgetn_wstr,  mvh­
       line_set,  mvin_wch,  mvinnwstr,  mvins_nwstr,  mvins_wch,
       mvins_wstr, mvinwchnstr, mvinwchstr, mvinwchstr, mvinwstr,
       mvvline_set,  mvwadd_wch,  mvwadd_wchnstr,  mvwadd_wchstr,
       mvwaddnwstr,	mvwaddwstr,	mvwget_ch,    mvwget_wch,
       mvwget_wstr,   mvwgetn_wstr,   mvwhline_set,    mvwin_wch,
       mvwin_wchnstr,	mvwin_wchstr,  mvwinnwstr,  mvwins_nwstr,
       mvwins_wch, mvwins_wstr, mvwinwchnstr.	mvwinwstr,  mvwv­
       line_set,  pecho_wchar,	setcchar,  slk_wset,  term_attrs,
       unget_wch,  vhline_set,	vid_attr,  vid_puts,   vline_set,
       wadd_wch,  wadd_wchnstr, wadd_wchstr, waddnwstr, waddwstr,
       waddwstr, wbkgrnd,  wbkgrndset,	wbkgrndset,  wborder_set,
       wecho_wchar, wecho_wchar, wget_wch, wget_wstr, wgetbkgrnd,
       wgetn_wstr, whline_set, win_wch, win_wchnstr,  win_wchstr,
       winnwstr,  wins_nwstr,  wins_wch,  wins_wstr,  winwchnstr,
       winwchstr, winwstr, wunctrl, wvline_set,

       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.

       The  routine  slk_attr is not part of XPG4, nor is it pre­
       sent in	SVr4.	See  the  curs_slk(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 wresize is not part of XPG4, nor is it present
       in SVr4.  See the wresize(3X) manual page for details.

							       15

ncurses(3X)					      ncurses(3X)

       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.

       In  the	XSI  standard  and  SVr4 manual pages, many entry
       points have prototype arguments of the for char *const (or
       cchar_t	*const,  or  wchar_t  *const,  or  void  *const).
       Depending on one's interpretation of the ANSI  C  standard
       (see  section  3.5.4.1), these declarations are either (a)
       meaningless, or (b) meaningless and illegal.  The declara­
       tion const char *x is a modifiable pointer to unmodifiable
       data, but char *const x' is  an	unmodifiable  pointer  to
       modifiable  data.  Given that C passes arguments by value,
       <type> *const as a formal type is at best  dubious.   Some
       compilers  choke  on  the  prototypes.  Therefore, in this
       implementation, they have been changed to const	<type>	*
       globally.

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 fea­
       ture 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.

							       16


NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ENVIRONMENT | FILES | SEE ALSO | EXTENSIONS | PORTABILITY | NOTES | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ncurses&sektion=3&manpath=FreeBSD+4.2-RELEASE>

home | help