X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_getch.3x;h=fed7fa70300050388f00bd7924d6b498022f1aac;hb=bd2d9c5734d2c66abe0b2ddd766695b200c154fe;hp=cf7225b6cf3436e156ef3771d557e43b507865e5;hpb=894a177fd5228cdbe790bd1dc9435bd435c29681;p=ncurses.git diff --git a/man/curs_getch.3x b/man/curs_getch.3x index cf7225b6..fed7fa70 100644 --- a/man/curs_getch.3x +++ b/man/curs_getch.3x @@ -1,6 +1,6 @@ '\" t .\"*************************************************************************** -.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 2018-2023,2024 Thomas E. Dickey * .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,8 +28,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_getch.3x,v 1.75 2023/10/07 21:19:07 tom Exp $ -.TH curs_getch 3X 2023-10-07 "ncurses 6.4" "Library calls" +.\" $Id: curs_getch.3x,v 1.78 2024/02/17 19:27:03 tom Exp $ +.TH curs_getch 3X 2024-02-17 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -59,7 +59,6 @@ get (or push back) characters from \fIcurses\fR terminal keyboard .PP .B int getch(void); .B int wgetch(WINDOW *\fIwin\fP); -.PP .B int mvgetch(int \fIy\fP, int \fIx\fP); .B int mvwgetch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP); .PP @@ -69,7 +68,7 @@ get (or push back) characters from \fIcurses\fR terminal keyboard .B int has_key(int \fIch\fP); .fi .SH DESCRIPTION -.SS Reading characters +.SS "Reading Characters" The \fBgetch\fP, \fBwgetch\fP, \fBmvgetch\fP and \fBmvwgetch\fP, routines read a character from the window. In no-delay mode, if no input is waiting, the value \fBERR\fP is returned. @@ -102,7 +101,7 @@ Otherwise the character is simply output to the screen. If the window is not a pad, and it has been moved or modified since the last call to \fBwrefresh\fP, \fBwrefresh\fP will be called before another character is read. -.SS Keypad mode +.SS "Keypad Mode" If \fBkeypad\fP is \fBTRUE\fP, and a function key is pressed, the token for that function key is returned instead of the raw characters: .bP @@ -129,18 +128,18 @@ otherwise, the function key value is returned. For this reason, many terminals experience a delay between the time a user presses the escape key and the escape is returned to the program. .PP -In \fBncurses\fP, the timer normally expires after +In \fI\%ncurses\fP, the timer normally expires after the value in \fBESCDELAY\fP (see \fBcurs_variables\fP(3X)). If \fBnotimeout\fP is \fBTRUE\fP, the timer does not expire; it is an infinite (or very large) value. Because function keys usually begin with an escape character, the terminal may appear to hang in notimeout mode after pressing the escape key until another key is pressed. -.SS Ungetting characters +.SS "Ungetting Characters" The \fBungetch\fP routine places \fIch\fP back onto the input queue to be returned by the next call to \fBwgetch\fP. There is just one input queue for all windows. -.SS Predefined key-codes +.SS "Predefined Key Codes" The following special keys are defined in \fB\fP. .bP Except for the special case \fBKEY_RESIZE\fP, @@ -280,10 +279,12 @@ This code is returned whether or not \fBkeypad\fP has been enabled. .B KEY_MOUSE is returned for mouse-events (see \fBcurs_mouse\fP(3X)). This code relies upon whether or not \fBkeypad\fP(3X) has been enabled, -because (e.g., with \fBxterm\fP(1) mouse prototocol) ncurses must -read escape sequences, +because +(e.g., +with \fBxterm\fP(1) mouse prototocol) +\fI\%ncurses\fP must read escape sequences, just like a function key. -.SS Testing key-codes +.SS "Testing Key Codes" The \fBhas_key\fP routine takes a key-code value from the above list, and returns \fBTRUE\fP or \fBFALSE\fP according to whether the current terminal type recognizes a key with that value. @@ -310,11 +311,16 @@ if there is no more room in the FIFO. .TP \fBwgetch\fP returns \fBERR\fP +.RS +.bP if the window pointer is null, or +.bP if its timeout expires without having any data, or +.bP if the execution was interrupted by a signal (\fBerrno\fP will be set to \fBEINTR\fP). .RE +.RE .PP Functions with a \*(``mv\*('' prefix first perform a cursor movement using \fBwmove\fP, and return an error if the position is outside the window, @@ -331,7 +337,7 @@ keys, e.g., Some curses implementations may differ according to whether they treat these control keys specially (and ignore the terminfo), or use the terminfo definitions. -\fBNcurses\fP uses the terminfo definition. +\fI\%ncurses\fP uses the terminfo definition. If it says that \fBKEY_ENTER\fP is control/M, \fBgetch\fP will return \fBKEY_ENTER\fP when you press control/M. @@ -369,39 +375,68 @@ consoles typically support little more than \fBKEY_UP\fP, \fBKEY_DOWN\fP, \fBKEY_NPAGE\fP, \fBKEY_PPAGE\fP, and function keys 1 through 12. The Ins key is usually mapped to \fBKEY_IC\fP. +.SH EXTENSIONS +\fB\%has_key\fP was designed for \fB\%ncurses\fP(3X), +and is not found in SVr4 +.IR curses , +4.4BSD +.IR curses , +or any other previous curses implementation. .SH PORTABILITY -The *get* functions are described in the XSI Curses standard, Issue 4. -They -read single-byte characters only. -The standard specifies that they return -\fBERR\fP on failure, but specifies no error conditions. +Applications employing +.I \%ncurses +extensions should condition their use on the visibility of the +.B \%NCURSES_VERSION +preprocessor macro. .PP -The echo behavior of these functions on input of \fBKEY_\fP or backspace -characters was not specified in the SVr4 documentation. -This description is -adopted from the XSI Curses standard. +X/Open Curses, Issue 4, Version 2, describes +\fB\%getch\fP, +\fB\%wgetch\fP, +\fB\%mvgetch\fP, +\fB\%mvwgetch\fP, +and +\fB\%ungetch\fP. +They read single-byte characters only. +The standard specifies that they return \fBERR\fP on failure, +but describes no failure conditions. .PP -The behavior of \fBgetch\fP and friends in the presence of handled signals is -unspecified in the SVr4 and XSI Curses documentation. -Under historical curses -implementations, it varied depending on whether the operating system's -implementation of handled signal receipt interrupts a \fBread\fP(2) call in -progress or not, and also (in some implementations) depending on whether an -input timeout or non-blocking mode has been set. +The echo behavior of these functions on input of +.B KEY_ +or backspace characters was not specified in the SVr4 documentation. +This description is adapted from X/Open Curses. .PP -\fBKEY_MOUSE\fP is mentioned in XSI Curses, along with a few related -terminfo capabilities, but no higher-level functions use the feature. -The implementation in ncurses is an extension. +The behavior of \fBgetch\fP and friends in the presence of signal +handlers is unspecified in the SVr4 documentation and X/Open Curses. +Under historical curses implementations, +it varied depending on whether the operating system's dispatch of a +signal to a handler interrupts a \fBread\fP(2) call in progress or not, +and also +(in some implementations) +whether an input timeout or non-blocking mode has been set. .PP -\fBKEY_RESIZE\fP is an extension first implemented for ncurses. -NetBSD curses later added this extension. +.B KEY_MOUSE +is mentioned in X/Open Curses, +along with a few related +.I \%term\%info +capabilities, +but no higher-level functions use the feature. +The implementation in +.I \%ncurses +is an extension. +.PP +.B KEY_RESIZE +is an extension first implemented for +.I \%ncurses. +NetBSD +.I curses +later added this extension. .PP Programmers concerned about portability should be prepared for either of two cases: (a) signal receipt does not interrupt \fBgetch\fP; (b) signal receipt interrupts \fBgetch\fP and causes it to return \fBERR\fP with \fBerrno\fP set to \fBEINTR\fP. .PP -The \fBhas_key\fP function is unique to \fBncurses\fP. +The \fBhas_key\fP function is unique to \fI\%ncurses\fP. We recommend that any code using it be conditionalized on the \fBNCURSES_VERSION\fP feature macro. .SH SEE ALSO