Unix/Linux Go Back    


SuSE 11.3 - man page for ncurses (suse section 3NCURSES)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


ncurses(3NCURSES)								ncurses(3NCURSES)

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 char-
       acter screens  with  reasonable	optimization.	This  implementation  is  ``new  curses''
       (ncurses)  and  is the approved replacement for 4.4BSD classic curses, which has been dis-
       continued.  This describes ncurses version 5.7 (patch 20100109).

       The ncurses library emulates the ncurses(3NCURSES) 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 PORTABIL-
       ITY sections below and described in detail in the respective EXTENSIONS,  PORTABILITY  and
       BUGS sections of individual man pages.

       The  ncurses  library also provides many useful extensions, i.e., features which cannot be
       implemented by a simple add-on library but which require access to the  internals  of  the
       library.

       A  program  using  these  routines must be linked with the -lncurses option, or (if it has
       been generated) with the 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  directory)  that
       describe curses actions.  See also the section on ALTERNATE CONFIGURATIONS.

       The  ncurses package supports: overall screen, window and pad manipulation; output to win-
       dows 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 pro-
       grams 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  ini-
       tialization  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 usu-
       ally responsible for doing this.  [See terminfo(5) for further details.]

       Beware:	the terminal your program is running may or may not have the features you expect.
       Ncurses makes no attempt to check available features in advance. This is upto the program-
       mer.

       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 sup-
       plied.  Others may be created with newwin.

       Note that curses does not handle overlapping windows, that's done  by  the  panel(3CURSES)
       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  unde-
       sired, 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 rou-
       tines 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 con-
       strained  to  the  size of the screen and whose contents need not be completely displayed.
       See pad(3NCURSES) for more information.

       In addition to drawing characters on the screen, video attributes and colors may  be  sup-
       ported,	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 func-
       tion 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 infor-
       mation 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/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/terminfo/a/att4424.

       This is useful for  developing  experimental  definitions  or  when  write  permission  in
       /usr/share/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 (See the sec-
		   tion on ALTERNATE CONFIGURATIONS).  The "wide" library  includes  all  of  the
		   calls  from	the  "normal"  library.  It adds about one third more calls using
		   data types which store multibyte 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.

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, getbe-
       gyx, and getmaxyx.  The return values of setscrreg, wsetscrreg, getyx, getbegyx, and  get-
       maxyx  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 redi-
	    rected 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.

	    Because this name is also used in development environments to represent  the  C  com-
	    piler's name, ncurses ignores it if it does not happen to be a single character.

       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 exe-
	    cuting.   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 use-
	    ful to circumvent legacy misfeatures of terminal descriptions, e.g., xterm which com-
	    monly  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 vari-
	    able 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 aux-
	    iliary 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(3NCURSES)).   You  may	set the foreground and background
	    color values with this environment	variable  by  proving  a  2-element  list:  fore-
	    ground,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  posi-
	    tive value from zero to the terminfo max_colors value is allowed.

       NCURSES_GPM_TERMS
	    This applies only to ncurses configured to use the GPM interface.

	    If	present, the environment variable is a list of one or more terminal names against
	    which the TERM environment variable is matched.  Setting it to an  empty  value  dis-
	    ables 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 con-
	    tains "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 high-
	    lighting 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 limi-
	    tations.  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 embed-
	    ded.  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 orig-
	    inal (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 corre-
	    spond 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 informa-
	    tion.   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  infor-
	    mation, 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/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: $TER-
       MINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.

ALTERNATE CONFIGURATIONS
       Several different configurations are possible, depending on the configure  script  options
       used when building ncurses.  There are a few main options whose effects are visible to the
       applications developer using ncurses:

       --disable-overwrite
	    The standard include for ncurses is as noted in SYNOPSIS:

	    #include <curses.h>

	    This option is used to avoid filename conflicts when ncurses is not the  main  imple-
	    mentation of curses of the computer.  If ncurses is installed disabling overwrite, it
	    puts its headers in a subdirectory, e.g.,

	    #include <ncurses/curses.h>

	    It also omits a symbolic link which would allow you to use -lcurses to build executa-
	    bles.

       --enable-widec
	    The  configure  script  renames the library and (if the --disable-overwrite option is
	    used) puts the header files in a different subdirectory.  All of  the  library  names
	    have a "w" appended to them, i.e., instead of

	    -lncurses

	    you link with

	    -lncursesw

	    You  must  also  define  _XOPEN_SOURCE_EXTENDED when compiling for the wide-character
	    library to use the extended (wide-character) functions.  The curses.h file	which  is
	    installed for the wide-character library is designed to be compatible with the normal
	    library's header.  Only the size of the WINDOW structure differs, and very few appli-
	    cations  require more than a pointer to WINDOWs.  If the headers are installed allow-
	    ing overwrite, the wide-character library's headers  should  be  installed	last,  to
	    allow applications to be built using either library from the same set of headers.

       --with-shared

       --with-normal

       --with-debug

       --with-profile
	    The  shared  and  normal (static) library names differ by their suffixes, e.g., libn-
	    curses.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.

       --with-trace
	    The  trace function normally resides in the debug library, but it is sometimes useful
	    to configure this in the shared library.  Configure  scripts  should  check  for  the
	    function's existence rather than assuming it is always in the debug library.

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

SEE ALSO
       terminfo(5) and related 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/termcap file if the terminal setup code cannot find a terminfo entry corre-
       sponding 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 mouse(3NCURSES) 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(3NCURSES) and wresize(3NCURSES) 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(3NCURSES) key_defined(3NCURSES), and keyok(3NCURSES) 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 origi-
       nal  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 bet-
       ter  control  over  color  contrasts.   See  the  default_colors(3NCURSES) manual page for
       details.

       The ncurses library includes a function for directing  application  output  to  a  printer
       attached to the terminal device.  See the print(3NCURSES) 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
	    getch(3NCURSES) manual page for details.

	    The routine slk_attr is not part of XPG4,  nor  is	it  present  in  SVr4.	 See  the
	    slk(3NCURSES) 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
	    mouse(3NCURSES) manual page for details.

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

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

	    The WINDOW structure's internal details can be hidden from application programs.  See
	    opaque(3NCURSES) 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  <unc-
       trl.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.

										ncurses(3NCURSES)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 05:30 PM.