ncurses 5.7 - patch 20100731

[ncurses.git] / man / curs_getch.3x

diff --git a/man/curs_getch.3x b/man/curs_getch.3x
index 88003a5d9dda1c4572f9eca30c1f5281253ea038..e804165521cf2ba1cf29e7a0fde30f2deda9c161 100644 (file)
--- a/man/curs_getch.3x
+++ b/man/curs_getch.3x
@@ -1,6 +1,6 @@
 '\" t
 .\"***************************************************************************
-.\" Copyright (c) 1998-2002,2003 Free Software Foundation, Inc.              *
+.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc.              *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *
@@ -27,8 +27,10 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_getch.3x,v 1.24 2003/12/27 18:46:06 tom Exp $
+.\" $Id: curs_getch.3x,v 1.31 2010/01/30 21:29:04 tom Exp $
 .TH curs_getch 3X ""
+.na
+.hy 0
 .SH NAME
 \fBgetch\fR,
 \fBwgetch\fR,
@@ -36,6 +38,8 @@
 \fBmvwgetch\fR,
 \fBungetch\fR,
 \fBhas_key\fR \- get (or push back) characters from \fBcurses\fR terminal keyboard
+.ad
+.hy
 .SH SYNOPSIS
 \fB#include <curses.h>\fR
 .PP
@@ -67,7 +71,7 @@ specified timeout has been reached.
 Unless \fBnoecho\fR 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,
+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 \fBdelch\fR had been called.
 If the character value is any other \fBKEY_\fR define, the user is alerted
@@ -110,7 +114,6 @@ center tab(/) ;
 l l
 l l .
 \fIName\fR/\fIKey\fR \fIname\fR
-.PP
 KEY_BREAK/Break key
 KEY_DOWN/The four arrow keys ...
 KEY_UP
@@ -223,24 +226,38 @@ The \fBhas_key\fR 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.
+e.g., \fBKEY_RESIZE\fP and \fBKEY_MOUSE\fP.
+See \fBresizeterm\fR(3X) for more details about \fBKEY_RESIZE\fP, and
+\fBcurs_mouse\fR(3X) for a discussion of \fBKEY_MOUSE\fP.
 .PP
 .SH RETURN VALUE
 All routines return the integer \fBERR\fR upon failure and an integer value
 other than \fBERR\fR (\fBOK\fR in the case of ungetch()) upon successful
 completion.
+.RS
+.TP 5
+\fBungetch\fP
+returns an error
+if there is no more room in the FIFO.
+.TP 5
+\fBwgetch\fP
+returns an error
+if the window pointer is null, or
+if its timeout expires without having any data.
+.RE
 .SH 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.
 .PP
 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.
+keys, e.g., \fBKEY_ENTER\fP versus control/M, \fBKEY_BACKSPACE\fP versus control/H.
 Some curses implementations may differ according to whether they
 treat these control keys specially (and ignore the terminfo), or
 use the terminfo definitions.
 \fBNcurses\fR uses the terminfo definition.
-If it says that KEY_ENTER is control/M, \fBgetch\fR will return KEY_ENTER
+If it says that \fBKEY_ENTER\fP is control/M,
+\fBgetch\fR will return \fBKEY_ENTER\fP
 when you press control/M.
 .PP
 When using \fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR, or
@@ -297,8 +314,12 @@ any code using it be conditionalized on the \fBNCURSES_VERSION\fR feature macro.
 \fBcurs_inopts\fR(3X),
 \fBcurs_mouse\fR(3X),
 \fBcurs_move\fR(3X),
-\fBcurs_refresh\fR(3X).
+\fBcurs_refresh\fR(3X),
 \fBresizeterm\fR(3X).
+.PP
+Comparable functions in the wide-character (ncursesw) library are
+described in
+\fBcurs_get_wch\fR(3X).
 .\"#
 .\"# The following sets edit modes for GNU EMACS
 .\"# Local Variables: