wgetch man page on MirBSD

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



curs_getch(3)	    UNIX Programmer's Manual	    curs_getch(3)

NAME
     getch, wgetch, mvgetch, mvwgetch, ungetch, has_key - get (or
     push back) characters from curses terminal keyboard

SYNOPSIS
     #include <curses.h>

     int getch(void);
     int wgetch(WINDOW *win);
     int mvgetch(int y, int x);
     int mvwgetch(WINDOW *win, int y, int x);
     int ungetch(int ch);
     int has_key(int ch);

DESCRIPTION
     The getch, wgetch, mvgetch and  mvwgetch,	routines  read	a
     character	from the window. In no-delay mode, if no input is
     waiting, the value ERR is returned. In delay mode, the  pro-
     gram  waits until the system passes text through to the pro-
     gram. Depending on the setting of cbreak, this is after  one
     character	(cbreak	 mode),	 or after the first newline (noc-
     break mode). In half-delay mode, the program waits	 until	a
     character	is  typed  or  the  specified  timeout	has  been
     reached.

     Unless noecho has been set, then the character will also  be
     echoed into the designated window according to the following
     rules: If the character is the current erase character, left
     arrow,  or	 backspace,  the cursor is moved one space to the
     left and that screen position is erased as if delch had been
     called. If the character value is any other KEY_ define, the
     user is alerted with a beep call. Otherwise the character is
     simply output to the screen.

     If the window is not a pad, and it has been moved	or  modi-
     fied  since  the  last  call  to  wrefresh, wrefresh will be
     called before another character is read.

     If keypad is TRUE, and a function key is pressed, the  token
     for that function key is returned instead of the raw charac-
     ters. Possible function keys are defined  in  <curses.h>  as
     macros  with  values  outside  the range of 8-bit characters
     whose names begin with KEY_. Thus, a  variable  intended  to
     hold  the	return	value  of a function key must be of short
     size or larger.

     When a character that could be the beginning of  a	 function
     key is received (which, on modern terminals, means an escape
     character), curses sets a timer. If the remainder of the se-
     quence  does  not	come  in  within the designated time, the
     character is passed through;  otherwise,  the  function  key
     value  is	returned. For this reason, many terminals experi-

MirOS BSD #10-current	Printed 18.8.2011			1

curs_getch(3)	    UNIX Programmer's Manual	    curs_getch(3)

     ence a delay between the time a user presses the escape  key
     and the escape is returned to the program.

     The ungetch routine places ch back onto the input	queue  to
     be	 returned  by  the next call to wgetch. There is just one
     input queue for all windows.

     Function Keys
     The following function keys, defined in <curses.h>, might be
     returned  by getch if keypad has been enabled. Note that not
     all of these are necessarily  supported  on  any  particular
     terminal.

	   Name		   Key name
	   KEY_BREAK	   Break key
	   KEY_DOWN	   The four arrow keys ...
	   KEY_UP
	   KEY_LEFT
	   KEY_RIGHT
	   KEY_HOME	   Home key (upward+left arrow)
	   KEY_BACKSPACE   Backspace
	   KEY_F0	   Function keys; space for 64 keys
			   is reserved.
	   KEY_F(n)	   For 0 _ n _ 63
	   KEY_DL	   Delete line
	   KEY_IL	   Insert line
	   KEY_DC	   Delete character
	   KEY_IC	   Insert char or enter insert mode
	   KEY_EIC	   Exit insert char mode
	   KEY_CLEAR	   Clear screen
	   KEY_EOS	   Clear to end of screen
	   KEY_EOL	   Clear to end of line
	   KEY_SF	   Scroll 1 line forward
	   KEY_SR	   Scroll 1 line backward (reverse)
	   KEY_NPAGE	   Next page
	   KEY_PPAGE	   Previous page
	   KEY_STAB	   Set tab
	   KEY_CTAB	   Clear tab
	   KEY_CATAB	   Clear all tabs
	   KEY_ENTER	   Enter or send
	   KEY_SRESET	   Soft (partial) reset
	   KEY_RESET	   Reset or hard reset
	   KEY_PRINT	   Print or copy
	   KEY_LL	   Home down or bottom (lower left)
	   KEY_A1	   Upper left of keypad
	   KEY_A3	   Upper right of keypad
	   KEY_B2	   Center of keypad
	   KEY_C1	   Lower left of keypad
	   KEY_C3	   Lower right of keypad
	   KEY_BTAB	   Back tab key
	   KEY_BEG	   Beg(inning) key
	   KEY_CANCEL	   Cancel key

MirOS BSD #10-current	Printed 18.8.2011			2

curs_getch(3)	    UNIX Programmer's Manual	    curs_getch(3)

	   KEY_CLOSE	   Close key
	   KEY_COMMAND	   Cmd (command) key
	   KEY_COPY	   Copy key
	   KEY_CREATE	   Create key
	   KEY_END	   End key
	   KEY_EXIT	   Exit key
	   KEY_FIND	   Find key
	   KEY_HELP	   Help key
	   KEY_MARK	   Mark key
	   KEY_MESSAGE	   Message key
	   KEY_MOUSE	   Mouse event read
	   KEY_MOVE	   Move key
	   KEY_NEXT	   Next object key
	   KEY_OPEN	   Open key
	   KEY_OPTIONS	   Options key
	   KEY_PREVIOUS	   Previous object key
	   KEY_REDO	   Redo key
	   KEY_REFERENCE   Ref(erence) key
	   KEY_REFRESH	   Refresh key
	   KEY_REPLACE	   Replace key
	   KEY_RESIZE	   Screen resized
	   KEY_RESTART	   Restart key
	   KEY_RESUME	   Resume key
	   KEY_SAVE	   Save key
	   KEY_SBEG	   Shifted beginning key
	   KEY_SCANCEL	   Shifted cancel key
	   KEY_SCOMMAND	   Shifted command key
	   KEY_SCOPY	   Shifted copy key
	   KEY_SCREATE	   Shifted create key
	   KEY_SDC	   Shifted delete char key
	   KEY_SDL	   Shifted delete line key
	   KEY_SELECT	   Select key
	   KEY_SEND	   Shifted end key
	   KEY_SEOL	   Shifted clear line key
	   KEY_SEXIT	   Shifted exit key
	   KEY_SFIND	   Shifted find key
	   KEY_SHELP	   Shifted help key
	   KEY_SHOME	   Shifted home key
	   KEY_SIC	   Shifted input key
	   KEY_SLEFT	   Shifted left arrow key
	   KEY_SMESSAGE	   Shifted message key
	   KEY_SMOVE	   Shifted move key
	   KEY_SNEXT	   Shifted next key
	   KEY_SOPTIONS	   Shifted options key
	   KEY_SPREVIOUS   Shifted prev key
	   KEY_SPRINT	   Shifted print key
	   KEY_SREDO	   Shifted redo key
	   KEY_SREPLACE	   Shifted replace key
	   KEY_SRIGHT	   Shifted right arrow
	   KEY_SRSUME	   Shifted resume key
	   KEY_SSAVE	   Shifted save key
	   KEY_SSUSPEND	   Shifted suspend key

MirOS BSD #10-current	Printed 18.8.2011			3

curs_getch(3)	    UNIX Programmer's Manual	    curs_getch(3)

	   KEY_SUNDO	   Shifted undo key
	   KEY_SUSPEND	   Suspend key
	   KEY_UNDO	   Undo key

     Keypad is arranged like this:

			_____________________
		       |  A1 |	 up |	A3  |
		       |_____|______|_______|
		       | left|	 B2 |  right|
		       |_____|______|_______|
		       |  C1 |	down|	C3  |
		       |_____|______|_______|

     The has_key routine takes a key value from the  above  list,
     and  returns  TRUE or FALSE according to whether the current
     terminal type recognizes a key with that value. Note that	a
     few values do not correspond to a real key, e.g., KEY_RESIZE
     and KEY_MOUSE. See	 resizeterm(3)	for  more  details  about
     KEY_RESIZE, and curs_mouse(3) for a discussion of KEY_MOUSE.

RETURN VALUE
     All routines return the integer ERR upon failure and an  in-
     teger  value  other  than	ERR (OK in the case of ungetch())
     upon successful completion.

	  ungetch
	       returns an error if there is no more room  in  the
	       FIFO.

	  wgetch
	       returns an error if the window pointer is null, or
	       if its timeout expires without having any data.

NOTES
     Use of the escape key by a programmer for a single character
     function  is  discouraged, as it will cause a delay of up to
     one second while the  keypad  code	 looks	for  a	following
     function-key sequence.

     Note that some keys may be the same as commonly used control
     keys, e.g., KEY_ENTER versus control/M, KEY_BACKSPACE versus
     control/H. Some curses implementations may differ	according
     to	 whether they treat these control keys specially (and ig-
     nore the terminfo), or use the terminfo definitions. Ncurses
     uses  the	terminfo definition. If it says that KEY_ENTER is
     control/M,	 getch	will  return  KEY_ENTER	 when  you  press
     control/M.

     When using getch, wgetch,	mvgetch,  or  mvwgetch,	 nocbreak
     mode  (nocbreak)  and echo mode (echo) should not be used at
     the same time. Depending on the state of the tty driver when

MirOS BSD #10-current	Printed 18.8.2011			4

curs_getch(3)	    UNIX Programmer's Manual	    curs_getch(3)

     each character is typed, the program may produce undesirable
     results.

     Note that getch, mvgetch, and mvwgetch may be macros.

     Historically, the set of keypad macros was	 largely  defined
     by	 the  extremely	 function-key-rich  keyboard  of the AT&T
     7300, aka 3B1, aka Safari 4. Modern personal computers  usu-
     ally  have	 only  a small subset of these. IBM PC-style con-
     soles typically support little more than  KEY_UP,	KEY_DOWN,
     KEY_LEFT,	  KEY_RIGHT,	KEY_HOME,   KEY_END,   KEY_NPAGE,
     KEY_PPAGE, and function keys 1 through 12. The  Ins  key  is
     usually mapped to KEY_IC.

PORTABILITY
     The *get* functions are described in the  XSI  Curses  stan-
     dard,  Issue  4.  They read single-byte characters only. The
     standard specifies that they  return  ERR	on  failure,  but
     specifies no error conditions.

     The echo behavior of these functions on  input  of	 KEY_  or
     backspace	characters was not specified in the SVr4 documen-
     tation. This description is  adopted  from	 the  XSI  Curses
     standard.

     The behavior of getch and friends in the presence of handled
     signals is unspecified in the SVr4 and XSI Curses documenta-
     tion. Under historical  curses  implementations,  it  varied
     depending	on  whether the operating system's implementation
     of handled signal receipt interrupts a read(2) call in  pro-
     gress  or	not, and also (in some implementations) depending
     on whether an input timeout or non-blocking  mode	has  been
     set.

     Programmers concerned about portability should  be	 prepared
     for  either of two cases: (a) signal receipt does not inter-
     rupt getch; (b) signal receipt interrupts getch  and  causes
     it	 to return ERR with errno set to EINTR. Under the ncurses
     implementation, handled signals never interrupt getch.

     The has_key function is unique to ncurses. We recommend that
     any  code using it be conditionalized on the NCURSES_VERSION
     feature macro.

SEE ALSO
     curses(3),	 curs_inopts(3),   curs_mouse(3),   curs_move(3),
     curs_refresh(3), resizeterm(3).

MirOS BSD #10-current	Printed 18.8.2011			5

[top]

List of man pages available for MirBSD

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