curses man page on SmartOS

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


       curses - introduction and overview of X/Open Curses

       The  Curses screen management package conforms fully with Issue 4, Ver‐
       sion 2 of the  X/Open Curses specification.    It  provides  a  set  of
       internationalized  functions  and  macros  for  creating and  modifying
       input and output to a terminal screen.	This  includes	functions  for
       creating	 windows,  highlighting	 text, writing to  the screen, reading
       from user input, and moving the cursor.

       X/Open Curses is a terminal-independent	package,  providing  a	common
       user  interface	to  a  variety of terminal types.  Its portability  is
       facilitated by the Terminfo database which contains a compiled  defini‐
       tion  of	 each terminal type.  By referring to the database information
       X/Open Curses gains access to low-level details about individual termi‐

       X/Open  Curses tailors its activities to the terminal type specified by
       the TERM environment variable.  The  TERM environment  variable may  be
       set in the Korn Shell (see ksh(1)) by typing:

	 export TERM=terminal_name

       To  set	environment  variables	using other command line interfaces or
       shells, see the environ(5) manual page.

       Three additional environment variables are useful, and can  be  set  in
       the Korn Shell:

	   1.	  If you have an alternate Terminfo database containing termi‐
		  nal types that are not available in the system default data‐
		  base	/usr/share/lib/terminfo, you can specify the  TERMINFO
		  environment variable to point to this alternate database:

		    export TERMINFO=path

		  This path specifies the location of the  alternate  compiled
		  Terminfo  database  whose  structure	consists  of directory
		  names 0 to 9 and a to z  (which represent the	 first	letter
		  of the compiled terminal definition file  name).

		  The  alternate  database specified by	 TERMINFO is  examined
		  before the system default database.  If  the	terminal  type
		  specified  by	  TERM cannot be found in either database, the
		  default terminal type dumb is assumed.

	   2.	  To specify a window width smaller  than  your	 screen	 width
		  (for	example,  in situations where your communications line
		  is slow), set the  COLUMNS environment  variable to the num‐
		  ber of vertical columns you want between the left and	 right

		    export COLUMNS=number

		  The number of columns may be set to a	 number	 smaller  than
		  the  screen  size; however, if set larger than the screen or
		  window width, the results are undefined.

		  The value set using this environment variable	 takes	prece‐
		  dence over the  value normally used for the terminal.

	   3.	  To  specify a window height smaller than your current screen
		  height (for example, in situations where your communications
		  line	is  slow),  override the LINES environment variable by
		  setting it to a smaller number of horizontal lines:

		    export LINES=number

		  The number of lines may be set to a number smaller than  the
		  screen  height;  however,  if	 set larger than the screen or
		  window height, the results are undefined.

		  The value set using this environment variable	 takes	prece‐
		  dence over the value normally used for the terminal.

   Data Types
       X/Open Curses defines the following data types:

		   An integral type that holds an OR-ed set of attributes. The
		   attributes acceptable are those which begin	with  the  WA_
		   prefix .

		   Boolean data type.

		   A type that refers to a string consisting of a spacing wide
		   character, up to  5 non-spacing wide characters,  and  zero
		   or  more  attributes	 of  any  type.	 See Attributes, Color
		   Pairs, and Renditions. A  null  cchar_t  object  terminates
		   arrays of cchar_t objects.

		   An  integral	 type  whose  values  are  formed by OR-ing an
		   "unsigned char" with a color pair.  and with zero  or  more
		   attributes. The attributes acceptable are those which begin
		   with the A_ prefix and COLOR_PAIR(3XCURSES)

		   An opaque data type associated with	a  terminal's  display

		   An opaque data type associated with a terminal. It contains
		   information about the terminal's capabilities  (as  defined
		   by  terminfo),  the	terminal  modes,  and current state of
		   input/output operations.

		   An integral data type whose values represent	 wide  charac‐

		   An opaque data type associated with a window.

   Screens, Windows, and Terminals
       The X/Open Curses manual pages refer at various points to screens, win‐
       dows (also subwindows, derived windows, and pads), and  terminals.  The
       following list defines each of these terms.

		 A  screen is a terminal's physical output device.  The SCREEN
		 data type is associated with a terminal.

		 Window objects are two-dimensional arrays of  characters  and
		 their	renditions.   X/Open Curses provides stdscr, a default
		 window which is the size of of the terminal screen.  You  can
		 use the newwin(3XCURSES) function to create others.

       To  refer  to  a	 window,  use  a variable declared as WINDOW *. X/Open
       Curses includes both functions that modify  stdscr,  and	 more  general
       versions that let you specify a window.

       There are three sub-types of windows:

			 A window which has been created within another window
			 (the parent window) and whose position has been spec‐
			 ified	with  absolute	screen	coordinates.  The der‐
			 win(3XCURSES) and subwin(3XCURSES) functions  can  be
			 used to create	 subwindows.

       Derived Window
			 A subwindow whose position is defined relative to the
			 parent window's coordinates rather than  in  absolute

			 A  special type of window that can be larger than the
			 screen.  For  more   information,   see   the	  new‐
			 pad(3XCURSES) man page.

			 A terminal is the input and output device which char‐
			 acter-based applications use  to  interact  with  the
			 user.	The TERMINAL data type is associated with such
			 a device.

   Attributes, Color Pairs, and Renditions
       A character's rendition consists of its attributes (such as underlining
       or  reverse  video)  and	 its color pair (the foreground and background
       colors).	   When	   using    waddstr(3XCURSES),	  waddchstr(3XCURSES),
       wprintw(3XCURSES),  winsch(3XCURSES), and so on, the window's rendition
       is combined with that character's renditions. The window	 rendition  is
       the   attributes	  and  color  set  using  the	attroff(3XCURSES)  and
       attr_off(3XCURSES) sets of functions. The window's background character
       and   rendition	 are  set  with	 the   bkgdset(3XCURSES)  and  bkgrnd‐
       set(3XCURSES) sets of functions.

       When spaces are written to the screen,  the  background	character  and
       window rendition replace the space. For example, if the background ren‐
       dition and character is	A_UNDERLINE|'*', text written  to  the	window
       appears underlined and the spaces appear as underlined asterisks.

       Each character written retains the rendition that it has obtained. This
       allows the character to be copied "as is" to or from a window with  the
       addchstr(3XCURSES) or inch(3XCURSES) functions.

   A_ Constant Values for Attributes
       You  can	 specify  Attributes,  Color  Pairs, and Renditions attributes
       using the constants listed in the tables below. The following constants
       modify objects of type chtype:

       │  Constant		 Description	       │
       │A_ALTCHARSET   Alternate character set	       │
       │A_ATTRIBUTES   Bit-mask to extract attributes  │
       │A_BLINK	       Blinking			       │
       │A_BOLD	       Bold			       │
       │A_CHARTEXT     Bit-mask to extract a character │
       │A_COLOR	       Bit-mask	 to extract color-pair │
       │	       information		       │
       │A_DIM	       Half-bright		       │
       │A_INVIS	       Invisible		       │
       │A_PROTECT      Protected		       │
       │A_REVERSE      Reverse video		       │
       │A_STANDOUT     Highlights specific to terminal │
       │A_UNDERLINE    Underline		       │

   WA_ Constant Values for Attributes
       The following constants modify objects of type attr_t:

       │  Constant		  Description		│
       │WA_ALTCHARSET	Alternate character set		│
       │WA_ATTRIBUTES	Attribute mask			│
       │WA_BLINK	Blinking			│
       │WA_BOLD		Bold				│
       │WA_DIM		Half-bright			│
       │WA_HORIZONTAL	Horizontal highlight		│
       │WA_INVIS	Invisible			│
       │WA_LEFT		Left highlist			│
       │WA_LOW		Low highlist			│
       │WA_PROTECT	Protected			│
       │WA_REVERSE	Reverse video			│
       │WA_RIGHT	Right highlight			│
       │WA_STANDOUT	Highlights specific to terminal │
       │WA_TOP		Top highlight			│
       │WA_UNDERLINE	Underline			│
       │WA_VERTICAL	Vertical highlight		│

   Color Macros
       Colors always appear in pairs; the foreground color  of	the  character
       itself  and the background color of the field on which it is displayed.
       The following color macros are defined:

       │    Macro	Description │
       │COLOR_BLACK	Black	    │
       │COLOR_BLUE	Blue	    │
       │COLOR_GREEN	Green	    │
       │COLOR_CYAN	Cyan	    │
       │COLOR_RED	Red	    │
       │COLOR_MAGENTA	Magenta	    │
       │COLOR_YELLOW	Yellow	    │
       │COLOR_WHITE	White	    │

       Together, a character's attributes and its color pair form the  charac‐
       ter's  rendition. A character's rendition moves with the character dur‐
       ing any scrolling or insert/delete operations. If your  terminal	 lacks
       support	for  the  specified rendition, X/Open Curses may  substitute a
       different rendition.

       The  COLOR_PAIR(3XCURSES)  function  modifies  a	 chtype	 object.   The
       PAIR_NUMBER(3XCURSES)  function	extracts  the color pair from a chtype

   Functions for Modifying a Window's Color
       The following functions modify a window's color:

       │	Function		     Description	   │
       │attr_set(), wattr_set()	    Change the window's rendition. │
       │color_set(), wcolor_set()   Set the window's color	   │

   Non-Spacing Characters
       When the wcwidth(3C) function returns a width of zero for a  character,
       that  character	is called a non-spacing character. Non-spacing charac‐
       ters can be written to a window. Each non-spacing character is  associ‐
       ated with a spacing character (that is, one which does not have a width
       of zero) and modifies that character. You cannot address a  non-spacing
       character  directly. Whenever you perform an X/Open Curses operation on
       the associated character,  you are implicitly addressing the  non-spac‐
       ing character.

       Non-spacing  characters do not have a rendition. For functions that use
       wide characters and a rendition, X/Open Curses  ignores	any  rendition
       specified  for non-spacing characters. Multi-column characters have one
       rendition that applies to all columns spanned.

   Complex Characters
       The cchar_t date type represents a complex character. A complex charac‐
       ter may contain a spacing character, its associated non-spacing charac‐
       ters, and its rendition. This implementation of complex characters sup‐
       ports up to 5 non-spacing characters for each spacing character.

       When  a	cchar_t object representing a non-spacing complex character is
       written to the screen, its rendition is not used, but rather it becomes
       associated  with	 the rendition of the existing character at that loca‐
       tion. The setcchar(3XCURSES) function initializes  an  object  of  type
       cchar_t.	  The  getcchar(3XCURSES)  function extracts the contents of a
       cchar_t object.

   Display Operations
       In adding internationalization support to X/Open Curses, every  attempt
       was  made  to  minimize	the number of changes to the historical CURSES
       package. This enables programs written to use the historical  implemen‐
       tation of CURSES to use the internationalized version with little or no
       modification. The following rules apply to the internationalized X/Open
       Curses package:

	   o	  The  cursor  can  be placed anywhere in the window.	Window
		  and screen origins are (0,0).

	   o	  A multi-column character cannot be  displayed	 in  the  last
		  column,   because  the  character  would  appear  truncated.
		  Instead, the background character is displayed in  the  last
		  column  and the multi-column character appears at the begin‐
		  ning of the next line. This is called wrapping.

		  If the original line is the last line in the	scroll	region
		  and  scrolling  is enabled, X/Open Curses moves the contents
		  of each line in the region to the previous line.   The first
		  line	of  the region is lost. The last line of the scrolling
		  region contains any wrapped characters.   The	 remainder  of
		  that	line  is  filled  with	the  background	 character. If
		  scrolling is disabled, X/Open Curses truncates any character
		  that would extend past the last column of the screen.

	   o	  Overwrites  operate  on screen columns. If displaying a sin‐
		  gle-column or multi-column character results in  overwriting
		  only	a  portion  of a multi-column character or characters,
		  background characters	 are displayed in place	 of  the  non-
		  overwritten portions.

	   o	  Insertions  and  deletions  operate on whole characters. The
		  cursor is moved to the first column of the  character	 prior
		  to performing	 the operation.

   Overlapping Windows
       When  windows  overlap, it may be necessary to overwrite only part of a
       multi-column character.	 As  mentioned	earlier,  the  non-overwritten
       portions	 are  replaced	with the background character. This results in
       issues concerning  the  overwrite(3XCURSES),  overlay(3XCURSES),	 copy‐
       win(3XCURSES),  wnoutrefresh(3XCURSES),	and  wrefresh(3XCURSES)	 func‐

   Special Characters
       Some functions assign special meanings to certain special characters:

			     Moves the cursor one column towards the beginning
			     of	 the  line.   If the cursor was already at the
			     beginning of the line, it remains there. All sub‐
			     sequent  characters are added or inserted at this

       Carriage Return
			     Moves the cursor to the beginning of the  current
			     line.  If the cursor was already at the beginning
			     of the line, it  remains  there.  All  subsequent
			     characters are added or inserted at this point.

			     When  adding  characters, X/Open Curses fills the
			     remainder of the line with the background charac‐
			     ter  (effectively	truncating  the	 newline)  and
			     scrolls the window as described earlier. All sub‐
			     sequent  characters  are inserted at the start of
			     the new line.

			     When inserting characters,	 X/Open	 Curses	 fills
			     the  remainder  of	 the  line with the background
			     character	(effectively  truncating  the	line),
			     moves  the cursor to the beginning of a new line,
			     and scrolls the window as described earlier.  All
			     subsequent	 characters are placed at the start of
			     the new line.

			     moves subsequent characters  to  next  horizontal
			     tab strop. Default tab stops are set at 0, 8, 16,
			     and so on.

			     When  adding  or  inserting  characters,	X/Open
			     Curses  inserts  or adds the background character
			     into each column  until  the  next	 tab  stop  is
			     reached.  If  there are no remaining tab stops on
			     the current line, wrapping and   scrolling	 occur
			     as described earlier.

       Control Characters
			     When  X/Open  Curses  functions  perform  special
			     character processing, they convert control	 char‐
			     acters  to	 the ^X notation, where X is a single-
			     column character (uppercase, if it is  a  letter)
			     and writes that notation to the window. Functions
			     that retrieve text from the window will  retrieve
			     the converted notation not the original.

       X/Open  Curses  displays	 non-printable bytes, that have their high bit
       set, using the M-X meta notation where X is the non-printable byte with
       its high bit turned off.

   Input Processing
       There  are four input modes possible with X/Open Curses that affect the
       behavior of input functions like getch(3XCURSES) and getnstr(3XCURSES).

       Line Canonical (Cooked)
				  In line input mode, the terminal driver han‐
				  dles	the  input  of	line  units as well as
				  SIGERASE and SIGKILL	character  processing.
				  See termio(7I) for more information.

				  In  this  mode,  the	getch()	 and getnstr()
				  functions will not return until  a  complete
				  line	has  been read by the terminal driver,
				  at which point only the requested number  of
				  bytes/characters  are returned.  The rest of
				  the line unit remains	 unread	 until	subse‐
				  quent	 call  to  the	 getch()  or getnstr()

				  The	functions    nocbreak(3XCURSES)	   and
				  noraw(3XCURSES) are used to enter this mode.
				  These	 functions  are	  described   on   the
				  cbreak(3XCURSES) man page which also details
				  which termios flags are enabled.

				  Of  the  modes  available,  this  one	 gives
				  applications	the  least  amount  of control
				  over input.	However, it is the only	 input
				  mode possible on a block mode terminal.

       cbreak Mode
				  Byte/character input provides a finer degree
				  of control.	 The  terminal	driver	passes
				  each	byte  read  to the application without
				  interpreting erase and kill characters.   It
				  is  the application's responsibility to han‐
				  dle line editing. It is unknown whether  the
				  signal  characters  (SIGINTR,	 SIGQUIT, SIG‐
				  SUSP) and flow control characters (SIGSTART,
				  SIGSTOP)  are enabled.   To ensure that they
				  are, call the noraw() function  first,  then
				  call the cbreak() function.

       halfdelay Mode
				  This is the same as the cbreak() mode with a
				  timeout.   The terminal driver waits	for  a
				  byte	to  be	received  or  for  a  timer to
				  expire, in which case the  getch()  function
				  either  returns a byte or  ERR respectively.
				  This mode  overrides	timeouts  set  for  an
				  individual  window with the wtimeout() func‐

       raw Mode
				  This mode provides byte/character input with
				  the  most control for	 an application. It is
				  similar to cbreak() mode, but also  disables
				  signal  character  processing (SIGINTR, SIG‐
				  SUSP, SIGQUIT) and flow control   processing
				  (SIGSTART,  SIGSTOP) so that the application
				  can process  them as it wants.

       These modes affect all X/Open Curses input.  The default input mode  is
       inherited from the parent process when the  application starts up.

       A  timeout  similar to halfdelay(3XCURSES) can be applied to individual
       windows (see  timeout(3XCURSES)).  The  nodelay(3XCURSES)  function  is
       equivalent to setting wtimeout(3XCURSES) for a window with a zero time‐
       out (non-blocking) or infinite delay (blocking).

       To handle function keys, keypad(3XCURSES) must be enabled.   When it is
       enabled,	 the  getch()  function returns a KEY_ constant for a uniquely
       encoded key defined for that terminal.	When keypad() is disabled, the
       getch()	function  returns the  individual bytes composing the function
       key (see	 getch(3XCURSES) and  wget_wch(3XCURSES)).  By	default,  key‐
       pad() is disabled.

       When  processing	 function  keys,  once the first byte is recognized, a
       timer is set for each subsequent byte in the sequence.	If any byte in
       the  function  key  sequence is not received before the timer  expires,
       the bytes already received are pushed into a buffer  and	 the  original
       first byte is returned. Subsequent X/Open Curses input would take bytes
       from the buffer until exhausted,	 after which new input from the termi‐
       nal  will  be  requested.    Enabling and disabling of the function key
       interbyte timer is handled by  the notimeout(3XCURSES)  function.    By
       default, notimeout() is disabled (that is, the timer is used).

       X/Open  Curses  always  disables the terminal driver's echo processing.
       The echo(3XCURSES) and noecho(3XCURSES) functions control X/Open Curses
       software	  echoing.    When  software echoing is enabled, X/Open Curses
       input functions echo printable  characters, control keys, and meta keys
       in  the input window at the last cursor	position.   Functions keys are
       never echoed.   When software echoing is disabled, it is	 the  applica‐
       tion's responsibility to	 handle echoing.

       Example	1  Copying Single-Column Characters Over Single-Column Charac‐

       In the upcoming examples, some characters have special meanings:

	   o	  {, [, and ( represent the left halves of multi-column	 char‐
		  acters. }, ], and ) represent the corresponding right halves
		  of the same multi-column characters.

	   o	  Alphanumeric characters and periods  (.)  represent  single-
		  column characters.

	   o	  The number sign (#) represents the background character.

	 copywin(s, t, 0, 1, 0, 1, 1, 3, 0)

		     s		     t	       →     t
		 abcdef	       ......	       .bcd..
		 ghijkl	       ......	       .hij..

	 There are no special problems with this situation.

       Example 2 Copying Multi-column Characters Over Single-Column Characters

	 copywin(s, t, 0, 1, 0, 1, 1, 3, 0)

		     s		     t	       →     t
		 a[]def	       ......	       .[]d..
		 gh()kl	       ......	       .h()..

       There are no special problems with this situation.

       Example	3 Copying Single-Column Characters From Source Overlaps Multi-
       column Characters In Target

	 copywin(s, t, 0, 1, 0, 1, 1, 3, 0)

		     s		     t	       →     t
		 abcdef	       []....	       #bcd..
		 ghijk tol	  ...().	  .hij#.

       Overwriting multi-column characters in t has resulted in	 the  #	 back‐
       ground  characters  being required to erase the remaining halves of the
       target's multi-column characters.

       Example 4 Copy Incomplete Multi-column Characters From Source  To  Tar‐

	 copywin(s, t, 0, 1, 0, 1, 1, 3, 0)

		     s		     t	       →     t
		 []cdef	       123456	       []cd56
		 ghi()l	       789012	       7hi()2

       The ] and ( halves of the multi-column characters have been copied from
       the source and expanded in the target outside of the  specified	target

       Consider a pop-up dialog box that contains single-column characters and
       a base window that contains multi-column characters and you do the fol‐

	 save=dupwin(dialog);	  /* create backing store */
	 overwrite(cursor, save); /* save region to be overlayed */
	 wrefresh(dialog);	  /* display dialog */
	 wrefresh(save);	  /* restore screen image */
	 delwin(save);		  /* release backing store */

       You  can use code similar to this to implement generic popup() and pop‐
       down() routines in a variety of CURSES implementations (including   BSD
       UNIX, and UNIX System V). In the simple case where the base window con‐
       tains single-column characters  only, it would  correctly  restore  the
       image that appeared on the screen before	 the dialog box was displayed.

       However,	 with  multi-column characters, the overwrite() function might
       save  a	region	with  incomplete  multi-column	characters.  The  wre‐
       fresh(dialog)  statement results in the behavior described in example 3
       above. The behavior described in this  example  (that  is,  example  4)
       allows the wrefresh(save) statement to restore the window correctly.

       Example	5 Copying An Incomplete Multi-column Character To  Region Next
       To Screen Margin	 (Not A Window Edge)

	Two cases of copying an incomplete multi-column character to a	region
       next to a screen margin follow:

	 copywin(s, t, 0, 1, 0, 0, 1, 2, 0)

		     s		     t	       →     t
		 []cdef	       123456	       #cd456
		 ghijkl	       789012	       hij012

       The  background	character (#) replaces the ] character that would have
       been copied from the source, because it is not possible to  expand  the
       multi-column character to its complete form.

	 copywin(s, t, 0, 1, 0, 3, 1, 5, 0)

		     s		     t	       →     t
		 abcdef	       123456	       123bcd
		 ghi()l	       789012	       789hi#

       This  second  example is the same as the first, but with the right mar‐

       See attributes(5) for descriptions of the following attributes:

       │Interface Stability │ Standard	      │
       │MT-Level	    │ Unsafe	      │

       ksh(1),	   COLOR_PAIR(3XCURSES),     PAIR_NUMBER(3XCURSES),	addch‐
       str(3XCURSES),	       attr_off(3XCURSES),	    attroff(3XCURSES),
       bkgdset(3XCURSES),   bkgrndset(3XCURSES),    cbreak(3XCURSES),	 copy‐
       win(3XCURSES),  derwin(3XCURSES),  echo(3XCURSES),  getcchar(3XCURSES),
       getch(3XCURSES),	       getnstr(3XCURSES),	  halfdelay(3XCURSES),
       inch(3XCURSES),	   keypad(3XCURSES),	 libcurses(3XCURSES),	  new‐
       pad(3XCURSES), newwin(3XCURSES), nocbreak(3XCURSES), nodelay(3XCURSES),
       noecho(3XCURSES),     noraw(3XCURSES),	 notimeout(3XCURSES),	 over‐
       lay(3XCURSES),	 overwrite(3XCURSES),	  setcchar(3XCURSES),	  sub‐
       win(3XCURSES),	       timeout(3XCURSES),	  waddchstr(3XCURSES),
       waddstr(3XCURSES), wcwidth(3C),	wget_wch(3XCURSES),  winsch(3XCURSES),
       wnoutrefresh(3XCURSES),	wprintw(3XCURSES),  wrefresh(3XCURSES), wtime‐
       out(3XCURSES), attributes(5), environ(5), standards(5), termio(7I)

				  Jun 5, 2002		      CURSES(3XCURSES)

List of man pages available for SmartOS

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