curses man page on Tru64

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

curses(3)							     curses(3)

NAME
       curses - Terminal screen-handling and optimization package

SYNOPSIS
       c89 [flag...] file -l curses [library...]

       cc [flag...] file -lcurses [-llibrary...]

       #include <curses.h>

DESCRIPTION
       The Curses library routines give the user a terminal-independent method
       of updating character screens with reasonable optimization. A C program
       using  these routines must be compiled with the -l curses operand. (The
       cc command supports only -lcurses as an operand. The c89	 command  sup‐
       ports  -lcurses	in  addition to the space-separated format.) See NOTES
       for information about compiling in the  different  definition  environ‐
       ments  required	for  the  standard  and backward compatible subsets of
       functions, macros, and other definitions that the library supports.

       The Curses package allows: overall screen, window,  and	pad  manipula‐
       tion;  output to windows and pads; reading terminal input; control over
       terminal and Curses input and output options;  environment  query  rou‐
       tines;  color  manipulation;  use of soft label keys; terminfo database
       access; and access to low-level Curses routines.

   Screen, Windows, and Terminals
       A screen is the physical output device of the terminal.	In  Curses,  a
       SCREEN  data  type  is  an opaque data type associated with a terminal.
       Each window (described later) is associated with a SCREEN.

       The Curses library permits manipulation of data structures, called win‐
       dows,  which  can be thought of as two-dimensional arrays of characters
       and their renditions representing all or part of a terminal's  physical
       screen.	 Windows do not have to correspond to the entire screen. It is
       possible to create smaller windows and also to indicate that  a	window
       is  only partially visible on the screen. It is possible to create win‐
       dows larger than the terminal screen by using pads.  A  default	window
       called  stdscr,	which is the size of the terminal screen, is supplied.
       Other windows may be created with the newterm or newwin function.

       Windows are referred to by variables declared as WINDOW *.  These  data
       structures  are manipulated with routines described on Section 3 refer‐
       ence pages whose names begin “curs_”.  Among the	 most  basic  routines
       are  move  and  addch,  which manipulate the default window stdscr, and
       refresh, which tells Curses to update the user's terminal  screen  from
       stdscr. More general versions of these routines enable specific windows
       to be manipulated and refreshed.

       Each window has a flag to indicate whether the information in the  win‐
       dow could differ from the information displayed on the terminal device.
       Making any change to the contents of the window,	 moving	 or  modifying
       the  window, or setting the window's cursor position sets this flag (in
       other words, touches the window).  Refreshing the  window  clears  this
       flag.

       A  subwindow is a window, created within another window called the par‐
       ent window, and positioned relative to the parent window.  A  subwindow
       can  be created by calling derwin, subpad, or subwin. Changes to either
       the parent window or the subwindow affect both. Window clipping is  not
       a property of subwindows.

       The term ancestor refers to a window's parent, or its parent, or so on.

       Derived	windows	 are subwindows whose position is defined by reference
       to the parent window rather than in absolute screen coordinates.	  Oth‐
       erwise, derived windows are no different from subwindows.

       Special	windows called pads may also be manipulated.  Pads are windows
       that are not necessarily associated with a viewable part of the screen.
       Pads  can be larger than the size of the screen. Use a pad whenever the
       application requires a window that is larger than the terminal  screen.
       A subpad is a specialized case of a subwindow created within a pad. See
       curs_pad(3) for more information.

       A terminal is the logical input and output device through which charac‐
       ter-based  applications	interact  with the user. TERMINAL is an opaque
       data type associated with a terminal.  A TERMINAL data  structure  pri‐
       marily  contains information about the capabilities of the terminal, as
       defined by the terminfo database. A TERMINAL data structure  also  con‐
       tains  information about the terminal modes and current state for input
       and output operations.  Each screen is associated with a TERMINAL  data
       structure.

       In  addition  to	 drawing  characters  on  the screen, applications can
       include video attributes and colors, causing the characters to show  up
       in  such modes as underlined, reverse video, or color on terminals that
       support such display enhancements. Applications can also specify	 line-
       drawing characters as output.  On input, Curses can translate arrow and
       function keys that transmit escape sequences into  single  values.  The
       video  attributes, line-drawing characters, and input values use names,
       such as A_REVERSE, WA_UNDERLINE, ACS_VLINE,  ACS_HLINE,	and  KEY_LEFT,
       that  are defined in <curses.h>. If the environment variables LINES and
       COLUMNS are set, or if the program is executing in  a  window  environ‐
       ment, line and column information in the environment overrides informa‐
       tion read from the terminfo database. This would affect a program  run‐
       ning  in	 a window environment, for example, where the size of a screen
       is changeable.

       If the environment variable TERMINFO is defined, Curses	checks	for  a
       local  terminal	definition  before checking in the standard place. For
       example, if TERM is set to wyse150, then the standard pathname  of  the
       compiled terminal definition is /usr/share/lib/terminfo/w/wyse150. (The
       w in this path is copied from the first letter of wyse150 to avoid cre‐
       ation   of   huge   directories.)   However,  if	 TERMINFO  is  set  to
       $HOME/myterms, Curses first checks for $HOME/myterms/w/wyse150 and,  if
       no   definition	 is   found,   then   checks  for  /usr/share/lib/ter‐
       minfo/w/wyse150. The search path beginning with	$HOME  is  useful  for
       developing  and	testing experimental definitions or when write permis‐
       sion in /usr/share/lib/terminfo is not available.

       The integer variables LINES and COLS are defined in <curses.h> and  are
       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 variable can be used  in  only  a
       few routines.

   Multicolumn Characters
       Some character sets define multicolumn characters that occupy more than
       one column position when displayed on the screen.

       Writing a character whose width is greater than the width of the desti‐
       nation window is an error.

   Attributes
       Each  character	can be displayed with attributes, such as underlining,
       reverse video, or color on terminals that support such display enhance‐
       ments.  Current	attributes  of	a window are applied to all characters
       that are written into the window by waddch, wadd_wch, waddstr,  waddch‐
       str, waddwstr, waddwchstr, or wprintw.  Attributes can be combined.

       The  <curses.h> file defines constants that applications use to specify
       attributes. Names of these constants start with A_.  The	 A_  constants
       manipulate attributes in objects of type int. Additional attributes can
       be specified using constants with the WA_  prefix.  The	WA_  constants
       manipulate attributes in objects of type attr_t.

       Two  constants  that  begin with A_ and WA_ and that represent the same
       terminal capability refer to the same attribute in the  terminfo	 data‐
       base  and in the window data structure. The effect on a window does not
       differ depending on whether the application specifies A_	 or  WA_  con‐
       stants.	 For  example,	when  an application updates window attributes
       using the interfaces that support the A_ values, a query of the	window
       attribute  using	 the  function	that  returns WA_ values reflects this
       update. When it updates window attributes  using	 the  interfaces  that
       support	the  WA_  values,  for	which corresponding A_ values exist, a
       query of the window attribute using the function that returns A_ values
       reflects this update.

   Rendition
       The  rendition of a character displayed on the screen is its attributes
       and a color pair.

       The rendition of a character written to the screen becomes  a  property
       of  the	character and moves with the character through any of the fol‐
       lowing operations: Scrolling Line or character insertion Line or	 char‐
       acter deletion

       To  the	extent possible on a particular terminal, a character's rendi‐
       tion corresponds to the graphic rendition of the character put  on  the
       screen.

       If  a  given  terminal does not support a rendition that an application
       program is trying to use, Curses may substitute a different rendition.

       Colors are always used in pairs (referred to as color-pairs).  A color-
       pair  consists  of a foreground color (for characters) and a background
       color (for the field on which the characters are displayed).

   Nonspacing Characters
       Some character sets  may	 contain  nonspacing  characters.   Nonspacing
       characters  are	those  for  which wcwidth returns a width of zero. The
       application may write nonspacing characters to a	 window.   Every  non‐
       spacing	character  in  a window is associated with a spacing character
       and modifies the spacing character.  Nonspacing characters in a	window
       cannot  be  addressed separately.  A nonspacing character is implicitly
       addressed whenever a Curses operation  affects  the  spacing  character
       with which the nonspacing character is associated.

       Nonspacing  characters  do not support attributes.  For interfaces that
       use wide characters and attributes, the attributes are ignored  if  the
       wide  character is a nonspacing character.  Multicolumn characters have
       a single set of attributes for all columns.  The	 association  of  non‐
       spacing	characters  with  spacing  characters can be controlled by the
       application using the wide character  interfaces.   The	wide-character
       string functions provide codeset-dependent association.

       Two typical effects of a nonspacing character associated with a spacing
       character called c, are as follows: The nonspacing character may modify
       the  appearance	of c. For instance, there may be nonspacing characters
       that add diacritical marks to characters.  However, there may  also  be
       spacing	characters  with  built-in  diacritical marks.	The nonspacing
       character may bridge c to the character following c.  Examples of  this
       usage  are  the formation of ligatures and the conversion of characters
       into compound display forms, words, or ideograms.

   Complex Characters
       A complex character is  a  set  of  associated  characters,  which  may
       include	a spacing character, any nonspacing characters associated with
       it, or both.  A spacing complex character is a spacing  character  fol‐
       lowed  by  its  associated  nonspacing characters. A nonspacing complex
       character is one or more nonspacing characters  without	an  associated
       spacing character. An example of a coded character set that has complex
       characters is ISO/IEC 10646-1:1993.

       A complex character can be written to the screen. If the complex	 char‐
       acter  does  not include a spacing character, any nonspacing characters
       are associated with the spacing complex character that  exists  at  the
       specified screen position.  When the application reads information back
       from the screen, it obtains spacing complex characters.

       The cchar_t data type represents a complex character and its rendition.
       When  cchar_t  represents a complex character without a spacing charac‐
       ter, then its rendition is not used; when it is written to the  screen,
       it  uses	 the rendition specified by the spacing character already dis‐
       played.

       An object of type cchar_t can be initialized by using setcchar and  the
       object's	 contents can be extracted by using getcchar.  The behavior of
       functions that take a cchar_t input argument is undefined if the appli‐
       cation provides a cchar_t value that was not initialized in this way.

   Window Properties
       Windows	have the following properties that affect the placing of char‐
       acters in the window: Each window has a rendition,  which  is  combined
       with  the  rendition  component	of  the	 window's  background property
       (described next).  Each window has a background	property.   The	 back‐
       ground  property	 specifies  the following: A spacing complex character
       (the background character) that will be used in a variety of situations
       where  visible  information is deleted from the screen.	A rendition to
       use in displaying the background character in those situations, and  in
       other situations.

   Screen Addressing
       Many  Curses functions use a coordinate pair for screen addressing.  In
       the DESCRIPTION, coordinate locations are represented as (y,  x)	 since
       the  y  argument	 always	 precedes the x argument in the function call.
       These coordinates denote a line/column position, not a character	 posi‐
       tion.

       The coordinate y always refers to the row (of the window), and x always
       refers to the column.  The first row and the first column are  numbered
       0, not 1.  The position (0, 0) is the window's origin.

       For  example,  for  terminals that display the ISO 8859-1 character set
       (with left-to-right writing), (0, 0)  represents	 the  upper  left-hand
       corner of the screen.

       Functions that start with mv take arguments that specify a (y, x) posi‐
       tion and move the cursor (as though move were called) before performing
       the  requested action.  As part of the requested action, further cursor
       movement may occur as specified on the respective reference page.

   Adding (Overwriting) Characters
       The Curses functions that contain the word add, such as addch,  specify
       one or more characters to replace (overwrite) characters already in the
       window. If these functions specify only nonspacing characters, they are
       appended to a spacing character already in the window.

       When  replacing	a multicolumn character with a character that requires
       fewer columns, the new character is added starting at the specified  or
       implied column position.	 All columns that the former multicolumn char‐
       acter occupied that the new character does  not	require	 are  orphaned
       columns,	 which	are  filled  using the background character and window
       rendition.

       Replacing a character with a character that requires more columns  also
       replaces	 one  or more subsequent characters on the line.  This process
       may also produce orphaned columns.

   Truncation, Wrapping, and Scrolling
       If the application specifies a character or a string of characters such
       that  writing  them to a window would extend beyond the end of the line
       (for example, if the application tries to deposit any multicolumn char‐
       acter  at  the  last column in a line), the behavior depends on whether
       the function supports line wrapping: If the function does not wrap,  it
       fails.  If the function wraps, then it places one or more characters in
       the window at the start of the next  line,  beginning  with  the	 first
       character that would not completely fit on the original line.

	      If  the  final  character on the line is a multicolumn character
	      that does not completely fit on the line, the  entire  character
	      wraps  to	 the next line, and columns at the end of the original
	      line may be orphaned.

	      If the original line was the last line in the window,  the  wrap
	      may cause a scroll to occur as follows: If scrolling is enabled,
	      a scroll occurs. The contents of the first line  of  the	window
	      are  lost.   The	contents  of each remaining line in the window
	      move to the previous line.  The  last  line  of  the  window  is
	      filled with any characters that wrapped.	Any remaining space on
	      the last line is filled with the background character and rendi‐
	      tion.   If  scrolling  is	 disabled,  any	 characters that would
	      extend beyond the last column of the last	 line  are  truncated.
	      The scrollok function enables and disables scrolling.

       Some  add  functions  move  the	cursor just beyond the end of the last
       character added.	 If this position is beyond the end of a  line,	 wrap‐
       ping  and scrolling occur under the conditions specified in the preced‐
       ing list.

   Inserting Characters
       Insertion functions  (such  as  insch)  insert  characters  immediately
       before the character at the specified or current cursor position.

       The insertion shifts all characters that were formerly at or beyond the
       cursor position on the cursor line toward the end of  that  line.   The
       disposition  of the characters that would thus extend beyond the end of
       the line depends on whether the	function  supports  wrapping:  If  the
       function	 does  not wrap, those characters are removed from the window.
       This may produce orphaned columns.  If the function supports  wrapping,
       the effect is as described earlier.

       If  multicolumn	characters  are	 displayed,  some cursor positions are
       within a multicolumn character but not at the beginning of a character.
       Any request to insert data at a position that is not the beginning of a
       multicolumn character will be adjusted so that the actual cursor	 posi‐
       tion  is	 at  the  beginning  of the multicolumn character in which the
       requested position occurs.

       There are no warning indications relative  to  cursor  relocation.  The
       application  should not maintain an image of the cursor position, since
       this constitutes placing terminal-specific information in the  applica‐
       tion and defeats the purpose of using Curses.

       Portable applications cannot assume that a cursor position specified in
       an insert function is a reusable indication of the actual cursor	 posi‐
       tion.

   Deleting Characters
       Deletion functions (such as delch) delete the simple or complex charac‐
       ter at the specified or implied cursor position.	 Regardless  of	 which
       column  of  the character on which the cursor is positioned, all column
       positions are replaced by the background character  and	window	rendi‐
       tion.  The  cursor is not relocated.  If a character-deletion operation
       would cause a previous  wrapping	 operation  to	be  undone,  then  the
       results are unspecified.

   Window Operations
       Overlapping  a  window  (that is, placing one window on top of another)
       and overwriting a window (that is, copying the contents of  one	window
       into  another)  follows the operation of overwriting multicolumn glyphs
       around its edge.	 Any orphaned columns are handled as described in  the
       preceding sections on character operations.

   Characters that Straddle the Subwindow Border
       A  subwindow  can  be defined such that multicolumn characters straddle
       the subwindow border.  The character operations deal with these	strad‐
       dling characters as follows: Reading the subwindow with a function such
       as in_wch reads the entire straddling character.	 Adding, inserting, or
       deleting	 characters  in	 the  subwindow	 deletes the entire straddling
       character before the requested operation begins and does	 not  relocate
       the  cursor.   Scrolling	 lines	in  the	 subwindow  has	 the following
       effects: A straddling character at the start of the line is  completely
       erased  before  the scroll operation begins.  A straddling character at
       the end of the line moves in the direction of the scroll and  continues
       to straddle the subwindow border.  Column positions outside the subwin‐
       dow at the straddling character's former position are  orphaned	unless
       another straddling character scrolls into those positions.

       If the application calls a function such as border, the preceding situ‐
       ations do not occur because writing the border on the subwindow deletes
       any straddling characters.

       In  the	preceding  cases  involving multicolumn characters, operations
       confined to a subwindow can modify the screen  outside  the  subwindow.
       Therefore, saving a subwindow, performing operations within the subwin‐
       dow, and then restoring the subwindow may disturb the appearance of the
       screen.	 To  overcome these effects (for example, for pop-up windows),
       the application should refresh the entire screen.

   Special Characters
       The following table describes cursor movement that  results  from  pro‐
       cessing of special characters.

       In  Curses  functions that do not move the cursor based on the informa‐
       tion placed in the window, special characters are used  only  within  a
       string  to affect the placement of subsequent characters. In this case,
       the cursor movement described in the table does not persist in the vis‐
       ible cursor beyond the end of the operation.

       In  functions  that  do	move the cursor, the special characters can be
       used to affect the placement of subsequent characters  and  to  achieve
       movement of the visible cursor.

       ───────────────────────────────────────────────────────────────────────────
       Special Character   Effect on Cursor
       ───────────────────────────────────────────────────────────────────────────
       backspace	   Unless  the	cursor was already in column 0, backspace
			   moves the cursor one column toward the  start  of  the
			   current  line;  any characters after the backspace are
			   added or inserted starting there.
       carriage return	   Unless the cursor was already in  column  0,	 carriage
			   return  moves  the  cursor to the start of the current
			   line.  Any characters after the  carriage  return  are
			   added or inserted starting there.
       newline		   In  an add operation, Curses adds the background char‐
			   acter into successive columns until reaching	 the  end
			   of  the  line.  Scrolling occurs as described earlier.
			   Any	characters  after  the	newline	  character   are
			   inserted starting at the start of the new line.

			   In  an  insert  operation, newline moves the cursor to
			   the start of a new line.   Any  characters  after  the
			   newline  character  are placed at the start of the new
			   line.

			   The filter function may inhibit this processing.
       tab		   Tab characters in text move subsequent  characters  to
			   the	next  horizontal tab stop.  By default, tab stops
			   are in column 0, 8, 16, and so on.

			   In an insert or add operation, Curses inserts or adds,
			   respectively, the background character into successive
			   columns until reaching the next tab stop. If there are
			   no  more  tab  stops in the current line, wrapping and
			   scrolling occur as described earlier.
       ───────────────────────────────────────────────────────────────────────────

   Control Characters
       The Curses functions that perform special-character processing  concep‐
       tually  convert control characters to the caret (^) character, followed
       by a second character (which is an uppercase letter  if	it  is	alpha‐
       betic),	and  write  this  string to the window in place of the control
       character.  The functions that retrieve text from  the  window  do  not
       retrieve the original control character.

   Rendition of Characters Placed into a Window
       When the application adds or inserts characters into a window, assuming
       the character is not the space character, then the window receives  the
       following:  The character that the application specifies The color that
       the application specifies or the window color if the  application  does
       not specify a color The attributes specified

	      In  this	case,  a logically inclusive OR operation combines the
	      specified attributes with the window attributes.

       If the character that the application adds or inserts into a window  is
       the space character, then the window receives: The background character
       The color that the application specifies, or the window	color  if  the
       application does not specify a color The attributes specified

	      In  this	case,  a logically inclusive OR operation combines the
	      specified attributes with the window attributes.

   Input Processing
       The Curses input model provides a variety of ways to obtain input  from
       the keyboard.

   Keypad Processing
       The  application	 can  enable  or disable keypad translation by calling
       keypad.	When translation is enabled, Curses attempts  to  translate  a
       sequence	 of  terminal input that represents the pressing of a function
       key into a single key  code.   When  translation	 is  disabled,	Curses
       passes  terminal input to the application without such translation, and
       the application must interpret the input.

       The complete set of key codes for keypad keys that Curses  can  process
       is  specified  by the constants defined in <curses.h> whose names begin
       with KEY_. Each terminal type described in the  terminfo	 database  may
       support some or all of these key codes. The terminfo database specifies
       the sequence of input characters from the terminal type that correspond
       to each key code.

       Curses  cannot  translate  keypad  keys on terminals where pressing the
       keys does not transmit a unique sequence.

       When translation is enabled and a character that could be the beginning
       of  a  function key (such as escape) is received, Curses notes the time
       and begins accumulating	characters.   If  Curses  receives  additional
       characters  that	 represent  the	 pressing  of  a keypad key, within an
       unspecified interval from the time the first  character	was  received,
       then  Curses  converts this input to a key code for presentation to the
       application.  If such characters are not received during this interval,
       translation  of this input does not occur and the individual characters
       are presented to the application separately.  (Because Curses waits for
       this  interval  to  accumulate  a key code, many terminals experience a
       delay between the time a user presses the escape key and the  time  the
       escape is returned to the application.)

       In addition, No Timeout Mode provides that in any case where Curses has
       received part of a function key sequence, Curses waits indefinitely for
       the  complete key sequence.  The “unspecified interval” in the previous
       paragraph becomes infinite in No Timeout Mode.  No Timeout Mode	allows
       the  use	 of  function  keys over slow communication lines.  No Timeout
       Mode not only lets the user type the individual characters of  a	 func‐
       tion  key  sequence  but also delays application response when the user
       types a character (not a function key) that  begins  the	 function  key
       sequence.   For	this  reason,  in No Timeout Mode, many terminals will
       appear to hang between the time a user presses the escape key  and  the
       time  another key is pressed.  No Timeout Mode is switchable by calling
       notimeout.

       If any special characters are defined or	 redefined  to	be  characters
       that are members of a function key sequence, then Curses will be unable
       to recognize and translate those function keys.

       Several of the modes discussed in the next  section  are	 described  in
       terms of availability of input.	If keypad translation is enabled, then
       input is not available from the time Curses begins receiving  a	keypad
       sequence	 until the sequence is completely received or until the inter‐
       val has elapsed.

   Input Modes
       Four mutually-exclusive Curses input modes let the application  control
       the  effect  of	certain	 characters.  In the following table, the term
       “special characters” represents flow-control characters, the  interrupt
       character, the erase character, and the kill character:

       ─────────────────────────────────────────────────────────────────────────
       Input Mode	 Effect
       ─────────────────────────────────────────────────────────────────────────

       Cooked Mode	 This  mode  achieves  normal line-at-a-time processing
			 with all special characters handled outside the appli‐
			 cation. Cooked mode achieves the same effect as canon‐
			 ical-mode input processing as	specified  in  the  XBD
			 specification.	 The state of the ISIG and IXON options
			 are not changed upon entering	this  mode  by	calling
			 cbreak, and are set upon entering this mode by calling
			 noraw.
       cbreak Mode	 Characters typed by the user are immediately available
			 to the application and Curses does not perform special
			 processing on either the erase character or  the  kill
			 character.   An  application can select cbreak mode to
			 do its own line editing but to let the abort character
			 be  used  to  abort  the task.	 This mode achieves the
			 same effect as noncanonical mode, Case	 B  input  pro‐
			 cessing (with MIN set to 1 and ICRNL cleared) as spec‐
			 ified in the XBD specification.  The state of the ISIG
			 and  IXON  options  are not changed upon entering this
			 mode.
       Half-Delay Mode	 The effect is the same as  cbreak  Mode,  except  that
			 input functions wait until a character is available or
			 an interval defined by the application elapses, which‐
			 ever  comes first.  This mode achieves the same effect
			 as noncanonical mode, Case C  input  processing  (with
			 TIME set to the value specified by the application) as
			 specified in the XBD specification.  The state of  the
			 ISIG  and  IXON  options are not changed upon entering
			 this mode.
       Raw Mode		 Raw mode gives the application	 maximum  control  over
			 terminal input. The application sees each character as
			 it is typed.  This achieves the same  effect  as  non‐
			 canonical  mode,  Case D input processing as specified
			 in the XBD specification.  The ISIG and  IXON	options
			 are cleared upon entering this mode.
       ─────────────────────────────────────────────────────────────────────────

       The  terminal  interface	 settings  are recorded when the process calls
       initscr or newterm to initialize Curses	and  restores  these  settings
       when endwin is called.  The initial input mode for Curses operations is
       cbreak mode.

       The behavior of the Break key depends on	 other	bits  in  the  display
       driver that are not set by Curses.

   Delay Modes
       Two  mutually-exclusive	delay modes specify how quickly certain Curses
       functions return to the application when there  is  no  terminal	 input
       waiting when the function is called:

       No Delay	  The function fails.
       Delay	  The  application waits until the implementation passes
		  text through to the application.   If	 cbreak	 or  Raw
		  Mode	is  set,  the  application waits until after one
		  character is passed. Otherwise, the application  waits
		  until after the first newline, end-of-line, or end-of-
		  file character.

       The effect of No Delay Mode on function key processing is unspecified.

   Echo Processing
       Echo mode determines whether Curses  echoes  typed  characters  to  the
       screen.	The effect of Echo mode is analogous to the effect of the ECHO
       flag in the local mode field of the termios structure  associated  with
       the  terminal  device  connected to the window.	However, Curses always
       clears the ECHO flag while it is operating, to  inhibit	the  operating
       system  from  performing	 echoing.  The method of echoing characters is
       not identical to the operating system's method  of  echoing  characters
       because Curses performs additional processing of terminal input.

       If  in  Echo  mode,  Curses performs its own echoing. Any visible input
       character is stored in the current or specified	window	by  the	 input
       function that the application called, at that window's cursor position,
       as though addch were called, with all consequent effects such as cursor
       movement and wrapping.

       If not in Echo mode, the application must perform any echoing of input.
       Applications usually disable Echo Mode because they often perform their
       own echoing in a controlled area of the screen or do not echo at all.

   Initializing the Curses Environment
       To  initialize  the  Curses  environment, the application must call the
       initscr or newterm routine before using any of the other routines  that
       deal  with  windows  and	 screens. The application must call the endwin
       routine before exiting. To get character-at-a-time input without	 echo‐
       ing  (most  interactive,	 screen-oriented programs want this), applica‐
       tions should use the following sequence:

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

       Most applications also use the following sequence:

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

       Before a Curses program is run, the tab stops of the terminal should be
       set  and its initialization strings, if defined, must be output. Appli‐
       cations can do this by executing the tput init command after  exporting
       the  shell  environment	variable  TERM.	  (See terminfo(4) for further
       details.)

   Function Name Conventions
       The reference pages often present families  of  Curses  functions.  The
       names of different functions in each family include a basic name, which
       is combined with prefixes and infixes to indicate specific  programming
       options.	 The following list explains the naming conventions for Curses
       functions: A function with the basic name operates on the  window  std‐
       scr.   A	 function  with	 the same name plus the w prefix operates on a
       window specified by the win argument.

	      When the reference page for a  function  family  refers  to  the
	      “current	or  specified window,” this means stdscr for the func‐
	      tions whose names begin with the basic name and the window spec‐
	      ified by win for the functions whose names begin with w.

	      Functions whose names have the p prefix require an argument that
	      is a pad instead of a window.  A function with  the  basic  name
	      operates based on the current cursor position (of the current or
	      specified window, as described above).  A function with the same
	      name plus the mv prefix moves the cursor to a position specified
	      by the y and x arguments before performing the specified	opera‐
	      tion.

	      When  the	 reference  page  for  a function family refers to the
	      “current or specified position,” this means the cursor  position
	      for  the functions whose names begin with the basic name and the
	      position (y, x) for functions whose names begin with mv.

	      The mvw prefix also exists and combines the  mv  semantics  dis‐
	      cussed here with the w semantics discussed in the preceding list
	      item.  In the function argument list,  the  window  argument  is
	      always  specified before the arguments for coordinates.  A func‐
	      tion with the basic name is often provided for  historical  com‐
	      patibility and operates only on single-byte characters.  A func‐
	      tion with the same name  plus  the  w  infix  operates  on  wide
	      (multibyte)  characters.	A function with the same name plus the
	      _w infix operates on complex characters and their renditions.  A
	      particular  reference  page  discusses  functions in only one of
	      these three categories.  When a function	with  the  basic  name
	      operates	on  a  single  character  or a null-terminated string,
	      there is sometimes a function with the  same  name  plus	the  n
	      infix that operates on a specific number of characters.  In this
	      case, the function includes an n	argument  that	specifies  the
	      number  of characters to process.	 The respective reference page
	      specifies the outcome if the value of n is inappropriate.

   Function Families
       The following table lists each family of	 Curses	 functions.  The  “s”,
       “w”,  and  “c”  columns,	 whose entries are more fully explained in the
       Legend following the table, indicate  whether  the  function  processes
       special characters, performs wrapping, and advances the cursor.

       Function	 families  include  most,  but	not  all, the functions in the
       Curses library. See the section titled Index of	Routine	 Names	for  a
       complete	 and  alphabetically  ordered  list of Curses functions, along
       with the reference pages where they are described.

       ───────────────────────────────────────────────────────────────────────────
       Function Names	      Description			  s	w     c
       ───────────────────────────────────────────────────────────────────────────
			      Add (Overwrite) Family
       [mv][w]addch	      Add a character			  Y	Y     Y
       [mv][w]addch[n]str     Add a character string		  N	N     N
       [mv][w]add[n]str	      Add a string			  Y	Y     Y
       [mv][w]add[n]wstr      Add a wide character string	  Y	Y     Y
       [mv][w]add_wch	      Add a wide character  and	 rendi‐	  Y	Y     Y
			      tion
       [mv][w]add_wch[n]str   Add  an  array of wide characters	  ?	N     N
			      and renditions
			      Change Renditions Family
       [mv][w]chgat	      Change renditions	 of  characters	  -	N     N
			      in a window
			      Delete Family
       [mv][w]delch	      Delete a character		  -	-     N
			      Get  Family  (Get Input from Key‐
			      board to Window)
       [mv][w]getch	      Get a character			  Y	Y     Y

       [mv][w]get[n]str	      Get a character string		  Y	Y     Y
       [mv][w]get_wch	      Get a wide character		  Y	Y     Y
       [mv][w]get[n]_wstr     Get an array of  wide  characters	  Y	Y     Y
			      and key codes
			      Explicit Cursor Movement Family
       [w]move		      Move the cursor			  -	-     -
			      Input Family (Read Back From Win‐
			      dow)
       [mv][w]inch	      Input a character			  -	-     -
       [mv][w]inch[n]str      Input an array of characters  and	  -	-     -
			      attributes
       [mv][w]in[n]str	      Input a string			  -	-     -
       [mv][w]in[n]wstr	      Input a string of wide characters	  -	-     -
       [mv][w]in_wch	      Input a wide character and rendi‐	  -	-     -
			      tion
       [mv][w]in_wch[n]str    Input an array of wide characters	  -	-     -
			      and renditions
			      Insert Family
       [mv][w]insch	      Insert a character		  Y	N     N
       [mv][w]ins[n]str	      Insert a character string		  Y	N     N
       [mv][w]ins_[n]wstr     Insert a wide-character string	  Y	N     N
       [mv][w]ins_wch	      Insert a wide character		  Y	N     N
			      Print and Scan Family
       [mv][w]printw	      Print formatted output		  -	-     -
       [mv][w]scanw	      Convert formatted output		  -	-     -
       ───────────────────────────────────────────────────────────────────────────

       Legend

       The  following  notation indicates the effect when characters are moved
       to the screen.  (For functions in the Get family, this  effect  applies
       only when echoing is enabled.)

       s   Y  means these functions perform special-character process‐
	   ing.

	   N means they do not.

	   ? means the results are unspecified	when  these  functions
	   are applied to special characters.

	   - means this attribute does not apply to these functions.
       w   Y means these functions perform wrapping.

	   N means they do not.

	   - means this attribute does not apply to these functions.
       c   Y means these functions advance the cursor.

	   N means they do not.

	   - means this attribute does not apply to these functions.

   Index of Routine Names
       The  following index lists each Curses routine and the name of the ref‐
       erence page on which the routine is described.  An  asterisk  following
       the routine name indicates that it conforms to the X/Open UNIX standard
       (Version 4.2 of the X/Open Curses CAE specification).   curs_add_wch(3)
       curs_add_wchstr(3)  curs_add_wchstr(3)  curs_addch(3)  curs_addchstr(3)
       curs_addchstr(3)	   curs_addstr(3)    curs_addwstr(3)	curs_addstr(3)
       curs_addwch(3)	curs_addwchstr(3)   curs_addwchstr(3)  curs_addwstr(3)
       curs_attr_get(3)	 curs_attr_get(3)  curs_attr_get(3)   curs_attr_get(3)
       curs_attr(3)  curs_attr(3)  curs_attr(3) curs_termattrs(3) curs_beep(3)
       curs_bkgd(3) curs_bkgd(3) curs_bkgrnd(3) curs_bkgrnd(3)	curs_border(3)
       curs_border_set(3)   curs_border(3)   curs_border_set(3)	 curs_color(3)
       curs_inopts(3)	  curs_chgat(3)	    curs_clear(3)      curs_outopts(3)
       curs_clear(3)	   curs_clear(3)      curs_color(3)	 curs_color(3)
       curs_attr_get(3)	   curs_overlay(3)    curs_kernel(3)	curs_kernel(3)
       curs_kernel(3)	   curs_terminfo(3)	curs_util(3)	 curs_delch(3)
       curs_deleteln(3)	   curs_initscr(3)    curs_window(3)	curs_window(3)
       curs_refresh(3)	    curs_util(3)     curs_window(3)	curs_inopts(3)
       curs_add_wch(3)	  curs_addch(3)	    curs_addwch(3)     curs_initscr(3)
       curs_clear(3)	curs_termattrs(3)    curs_termattrs(3)	  curs_util(3)
       curs_beep(3)	curs_util(3)	 curs_get_wch(3)      curs_get_wstr(3)
       curs_getyx(3)	 curs_bkgrnd(3)	    curs_getch(3)     curs_getcchar(3)
       curs_getyx(3)	curs_get_wstr(3)    curs_getstr(3)     curs_getwstr(3)
       curs_getyx(3)  curs_getstr(3)  curs_getwch(3)  curs_util(3)  curs_getw‐
       str(3)  curs_getyx(3)  curs_inopts(3)  curs_color(3)  curs_termattrs(3)
       curs_termattrs(3)   curs_border(3)  curs_border_set(3)  curs_outopts(3)
       curs_outopts(3)	 curs_outopts(3)   curs_in_wch(3)    curs_in_wchstr(3)
       curs_in_wchstr(3)    curs_inch(3)    curs_inchstr(3)    curs_inchstr(3)
       curs_color(3)  curs_color(3)  curs_initscr(3)  curs_instr(3)  curs_inw‐
       str(3)  curs_ins_wstr(3) curs_ins_wch(3) curs_ins_wstr(3) curs_insch(3)
       curs_deleteln(3)	  curs_deleteln(3)   curs_insstr(3)    curs_inswstr(3)
       curs_insstr(3)	  curs_instr(3)	    curs_inswch(3)     curs_inswstr(3)
       curs_inopts(3)	 curs_inwch(3)	  curs_inwchstr(3)    curs_inwchstr(3)
       curs_inwstr(3) curs_touch(3) curs_touch(3) curs_initscr(3) curs_util(3)
       curs_util(3) curs_inopts(3) curs_termattrs(3) curs_outopts(3) curs_ter‐
       mattrs(3)  curs_inopts(3)  curs_move(3)	curs_add_wch(3)	 curs_add_wch‐
       str(3) curs_add_wchstr(3)  curs_addch(3)	 curs_addchstr(3)  curs_addch‐
       str(3)  curs_addstr(3)  curs_addwstr(3)	curs_addstr(3)	curs_addwch(3)
       curs_addwchstr(3)   curs_addwchstr(3)   curs_addwstr(3)	 curs_chgat(3)
       curs_terminfo(3)	    curs_delch(3)    curs_window(3)    curs_get_wch(3)
       curs_get_wstr(3)	   curs_getch(3)    curs_get_wstr(3)	curs_getstr(3)
       curs_getwstr(3) curs_getstr(3) curs_getwch(3) curs_getwstr(3) curs_bor‐
       der(3) curs_border_set(3) curs_in_wch(3) curs_in_wchstr(3) curs_in_wch‐
       str(3)	curs_inch(3)   curs_inchstr(3)	curs_inchstr(3)	 curs_instr(3)
       curs_inwstr(3)	 curs_ins_wstr(3)    curs_ins_wch(3)	 curs_insch(3)
       curs_insstr(3)	  curs_inswstr(3)     curs_insstr(3)	 curs_instr(3)
       curs_inswch(3)	 curs_inswstr(3)    curs_inwch(3)     curs_inwchstr(3)
       curs_inwchstr(3)	 curs_inwstr(3) curs_printw(3) curs_scanw(3) curs_bor‐
       der(3)	 curs_border_set(3)	curs_add_wch(3)	    curs_add_wchstr(3)
       curs_add_wchstr(3)   curs_addch(3)   curs_addchstr(3)  curs_addchstr(3)
       curs_addstr(3)	 curs_addwstr(3)     curs_addstr(3)	curs_addwch(3)
       curs_addwchstr(3)   curs_addwchstr(3)   curs_addwstr(3)	 curs_chgat(3)
       curs_delch(3)	curs_get_wch(3)	    curs_get_wstr(3)	 curs_getch(3)
       curs_get_wstr(3)	   curs_getstr(3)    curs_getwstr(3)	curs_getstr(3)
       curs_getwch(3)	curs_getwstr(3)	  curs_border(3)    curs_border_set(3)
       curs_window(3)	curs_in_wch(3)	 curs_in_wchstr(3)   curs_in_wchstr(3)
       curs_inch(3) curs_inchstr(3)  curs_inchstr(3)  curs_instr(3)  curs_inw‐
       str(3)  curs_ins_wstr(3) curs_ins_wch(3) curs_ins_wstr(3) curs_insch(3)
       curs_insstr(3) curs_insstr(3) curs_instr(3)  curs_inswch(3)  curs_insw‐
       str(3)  curs_inwch(3) curs_inwchstr(3) curs_in_wchstr(3) curs_inwstr(3)
       curs_printw(3)	 curs_scanw(3)	  curs_border(3)    curs_border_set(3)
       curs_kernel(3)  curs_pad(3)  curs_initscr(3)  curs_window(3)  curs_out‐
       opts(3) curs_inopts(3)  curs_inopts(3)  curs_inopts(3)  curs_outopts(3)
       curs_inopts(3) curs_inopts(3) curs_inopts(3) curs_overlay(3) curs_over‐
       lay(3) curs_color(3) curs_color(3) curs_pad(3) curs_pad(3)  curs_pad(3)
       curs_pad(3)  curs_pad(3)	 curs_printw(3)	 curs_terminfo(3) curs_util(3)
       curs_inopts(3) curs_inopts(3) curs_refresh(3) curs_refresh(3) curs_ker‐
       nel(3)  curs_kernel(3)  curs_kernel(3)  curs_terminfo(3) curs_kernel(3)
       curs_kernel(3)	 curs_scanw(3)	  curs_scr_dump(3)    curs_scr_dump(3)
       curs_scr_dump(3)	   curs_scr_dump(3)    curs_scroll(3)	curs_scroll(3)
       curs_outopts(3)	 curs_getcchar(3)   curs_terminfo(3)   curs_initscr(3)
       curs_outopts(3)	curs_terminfo(3)  curs_slk(3)  curs_slk(3) curs_slk(3)
       curs_slk(3) curs_slk(3) curs_slk(3) curs_slk(3) curs_slk(3) curs_slk(3)
       curs_slk(3) curs_slk(3) curs_slk(3) curs_slk(3) curs_slk(3) curs_slk(3)
       curs_slk(3)   curs_attr(3)   curs_attr(3)   curs_color(3)   curs_pad(3)
       curs_window(3)	curs_window(3)	 curs_termattrs(3)   curs_termattrs(3)
       curs_termattrs(3)   curs_termcap(3)   curs_termcap(3)   curs_termcap(3)
       curs_termcap(3)	 curs_termcap(3)   curs_terminfo(3)   curs_terminfo(3)
       curs_terminfo(3) curs_inopts(3) curs_touch(3)  curs_touch(3)  curs_ter‐
       minfo(3)	 curs_termcap(3)  curs_terminfo(3) curs_inopts(3) curs_util(3)
       curs_get_wch(3) curs_getch(3) curs_getwch(3) curs_touch(3) curs_util(3)
       curs_terminfo(3)	  curs_terminfo(3)  curs_border(3)  curs_border_set(3)
       curs_printw(3)	  curs_printw(3)      curs_scanw(3)	 curs_scanw(3)
       curs_add_wch(3)	 curs_add_wchstr(3)  curs_add_wchstr(3)	 curs_addch(3)
       curs_addchstr(3)	  curs_addchstr(3)   curs_addstr(3)    curs_addwstr(3)
       curs_addstr(3)	curs_addwch(3)	 curs_addwchstr(3)   curs_addwchstr(3)
       curs_addwstr(3)	curs_attr_get(3)   curs_attr_get(3)   curs_attr_get(3)
       curs_attr_get(3)	 curs_attr(3)  curs_attr(3)  curs_attr(3) curs_bkgd(3)
       curs_bkgd(3)  curs_bkgrnd(3)  curs_bkgrnd(3)  curs_border(3)  curs_bor‐
       der_set(3)   curs_chgat(3)  curs_clear(3)  curs_clear(3)	 curs_clear(3)
       curs_attr_get(3)	   curs_window(3)    curs_delch(3)    curs_deleteln(3)
       curs_addch(3)	  curs_addwch(3)     curs_add_wch(3)	 curs_clear(3)
       curs_get_wstr(3)	  curs_get_wch(3)    curs_get_wstr(3)	 curs_getch(3)
       curs_getstr(3)	  curs_getwstr(3)     curs_bkgrnd(3)	curs_getstr(3)
       curs_getwch(3)	curs_getwstr(3)	  curs_border(3)    curs_border_set(3)
       curs_in_wch(3)	 curs_in_wchstr(3)    curs_in_wchstr(3)	  curs_inch(3)
       curs_inchstr(3)	  curs_inchstr(3)     curs_instr(3)	curs_inwstr(3)
       curs_ins_wstr(3)	   curs_ins_wch(3)    curs_ins_wstr(3)	 curs_insch(3)
       curs_deleteln(3)	  curs_deleteln(3)   curs_insstr(3)    curs_inswstr(3)
       curs_insstr(3)	  curs_instr(3)	    curs_inswch(3)     curs_inswstr(3)
       curs_inwch(3)	curs_inwchstr(3)    curs_inwchstr(3)	curs_inwstr(3)
       curs_move(3)	curs_refresh(3)	    curs_printw(3)     curs_refresh(3)
       curs_refresh(3)	  curs_scanw(3)	    curs_scroll(3)     curs_outopts(3)
       curs_attr(3)  curs_attr(3) curs_window(3) curs_window(3) curs_inopts(3)
       curs_touch(3) curs_util(3) curs_border(3) curs_border_set(3)

NOTES
       The header file	<curses.h>  automatically  includes  the  header  file
       <stdio.h>.

       The  header files that supply function prototypes and other definitions
       for the Curses library support different	 definition  environments  for
       either  X/Open UNIX standard conformance or compatibility with versions
       of DIGITAL UNIX earlier than Version 4.0.

       The following list names and describes the  macros  that	 select	 these
       definition  environments:  Selects  APIs that conform to Version 4.2 of
       the  X/Open  Curses  CAE	 specification	 and   automatically   defines
       _XOPEN_SOURCE.

	      These  APIs were not available in the Curses library provided by
	      versions	of  DIGITAL  UNIX  earlier  than  Version   4.0.   The
	      _XOPEN_SOURCE_EXTENDED macro defines the recommended compilation
	      environment for all new Curses applications. Note that  the  c89
	      command  defines	_XOPEN_SOURCE_EXTENDED	by  default but the cc
	      command does not.

	      There  is	 no  difference	 between  _XOPEN_SOURCE_EXTENDED   and
	      _XOPEN_SOURCE=500	 with  respect to the Curses library.  Selects
	      the APIs that conform to Version 3  of  the  X/Open  Curses  CAE
	      specification.

	      These  APIs were not available in the Curses library provided by
	      versions of DIGITAL UNIX earlier than Version 4.0.  However,  as
	      of  Version 4.0, these APIs are defined within the _XOPEN_SOURCE
	      definition environment to meet the requirements  of  the	X/Open
	      Curses  CAE  specification.  Selects the System V Multi-National
	      Language Standard (MNLS) APIs, which are Curses  library	exten‐
	      sions for handling multibyte characters.

	      These  APIs were not available in the Curses library provided by
	      versions of DIGITAL UNIX earlier than Version 4.0. MNLS APIs are
	      supported	 only  for  backward  compatibility and are not recom‐
	      mended for use in new Curses applications.  The _OSF_SOURCE def‐
	      inition  environment should be used along with the _XOPEN_SOURCE
	      environment, so applications can access  MNLS  extensions	 along
	      with  generic  Curses  functions. Do not use the MNLS extensions
	      with the _XOPEN_SOURCE_EXTENDED  definition  environment,	 which
	      contains	a  different  set  of functions for handling multibyte
	      characters.  Selects the BSD Curses APIs.

	      These APIs were not available in the Curses library provided  by
	      versions	of DIGITAL UNIX earlier than Version 4.0. BSD APIs are
	      supported only for backward compatibility	 and  are  not	recom‐
	      mended  for  use in new Curses applications.  The BSD definition
	      environment is incompatible with all other  definition  environ‐
	      ments.  Selects the Minicurses APIs.

	      These  APIs were not available in the Curses library provided by
	      versions of DIGITAL UNIX earlier than  Version  4.0.  Minicurses
	      APIs  are	 supported only for backward compatibility and are not
	      recommended for use in new Curses applications.

       Refer to the standards(5) reference page for more information about the
       relationship  between  compilation definition environments and industry
       standards.

RETURN VALUES
       Unless otherwise noted  in  the	routine	 descriptions,	routines  that
       return  an  integer  return ERR upon failure and an integer value other
       than ERR upon successful completion.

       Routines that return pointers return NULL on error.

SEE ALSO
       See terminfo(4) and the Section 3 reference  pages  whose  names	 begin
       with “curs_” for detailed routine descriptions.

								     curses(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Tru64

List of man pages available for Tru64

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

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

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