ncurses 6.2 - patch 20210109
[ncurses.git] / man / curs_inopts.3x
index 69ad2c21fe2b964bd8356e051fa024d69313d40f..d346017ba0ea09dba6a0e38648c06578bf23a186 100644 (file)
@@ -1,5 +1,6 @@
 .\"***************************************************************************
-.\" Copyright (c) 1998-2016,2017 Free Software Foundation, Inc.              *
+.\" Copyright 2018-2019,2020 Thomas E. Dickey                                *
+.\" Copyright 1998-2016,2017 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            *
@@ -26,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_inopts.3x,v 1.24 2017/01/07 19:25:15 tom Exp $
+.\" $Id: curs_inopts.3x,v 1.33 2020/12/05 19:38:18 Benno.Schulenberg Exp $
 .TH curs_inopts 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
 \fBintrflush\fR,
 \fBkeypad\fR,
 \fBmeta\fR,
+\fBnl\fR,
+\fBnonl\fR,
 \fBnodelay\fR,
 \fBnotimeout\fR,
 \fBraw\fR,
 \fBnoraw\fR,
-\fBnoqiflush\fR,
 \fBqiflush\fR,
+\fBnoqiflush\fR,
 \fBtimeout\fR,
 \fBwtimeout\fR,
 \fBtypeahead\fR \- \fBcurses\fR input options
 \fBint cbreak(void);\fR
 .br
 \fBint nocbreak(void);\fR
-.br
+.sp
 \fBint echo(void);\fR
 .br
 \fBint noecho(void);\fR
+.sp
+\fBint intrflush(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
 .br
-\fBint halfdelay(int tenths);\fR
+\fBint keypad(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
 .br
-\fBint intrflush(WINDOW *win, bool bf);\fR
+\fBint meta(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
 .br
-\fBint keypad(WINDOW *win, bool bf);\fR
+\fBint nodelay(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
 .br
-\fBint meta(WINDOW *win, bool bf);\fR
-.br
-\fBint nodelay(WINDOW *win, bool bf);\fR
+\fBint notimeout(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
+.sp
+\fBint nl(void);\fR
 .br
+\fBint nonl(void);\fR
+.sp
 \fBint raw(void);\fR
 .br
 \fBint noraw(void);\fR
-.br
-\fBvoid noqiflush(void);\fR
-.br
+.sp
 \fBvoid qiflush(void);\fR
 .br
-\fBint notimeout(WINDOW *win, bool bf);\fR
-.br
-\fBvoid timeout(int delay);\fR
+\fBvoid noqiflush(void);\fR
+.sp
+\fBint halfdelay(int \fP\fItenths\fP\fB);\fR
 .br
-\fBvoid wtimeout(WINDOW *win, int delay);\fR
+\fBvoid timeout(int \fP\fIdelay\fP\fB);\fR
 .br
-\fBint typeahead(int fd);\fR
+\fBvoid wtimeout(WINDOW *\fP\fIwin\fP\fB, int \fP\fIdelay\fP\fB);\fR
+.sp
+\fBint typeahead(int \fP\fIfd\fP\fB);\fR
 .br
 .SH DESCRIPTION
 The \fBncurses\fP library provides several functions which let an application
@@ -101,7 +108,7 @@ windows.
 An application must apply these to each window, if the same behavior
 is needed.
 .\"
-.SS cbreak
+.SS cbreak/nocbreak
 Normally, the tty driver buffers typed characters until a newline or carriage
 return is typed.
 The \fBcbreak\fR routine disables line buffering and
@@ -140,7 +147,7 @@ The \fBhalfdelay\fR routine is used for half-delay mode, which is similar to
 \fBcbreak\fR mode in that characters typed by the user are immediately
 available to the program.
 However, after blocking for \fItenths\fR tenths of
-seconds, ERR is returned if nothing has been typed.
+seconds, \fBERR\fP is returned if nothing has been typed.
 The value of \fItenths\fR
 must be a number between 1 and 255.
 Use \fBnocbreak\fR to leave half-delay
@@ -178,7 +185,7 @@ The default value for keypad is \fBFALSE\fP.
 .SS meta
 .PP
 Initially, whether the terminal returns 7 or 8 significant bits on
-input depends on the control mode of the tty driver [see termio(7)].
+input depends on the control mode of the tty driver [see \fBtermios\fP(3)].
 To force 8 bits to be returned, invoke \fBmeta\fR(\fIwin\fR,
 \fBTRUE\fR); this is equivalent, under POSIX, to setting the CS8 flag
 on the terminal.
@@ -193,14 +200,20 @@ If the terminfo capabilities \fBsmm\fR
 \fBTRUE\fR) is called and \fBrmm\fR is sent when \fBmeta\fR(\fIwin\fR,
 \fBFALSE\fR) is called.
 .\"
+.SS nl/nonl
+.PP
+The \fBnl\fR and \fBnonl\fR routines control whether the underlying display
+device translates the return key into newline on input.
+.\"
 .SS nodelay
 .PP
 The \fBnodelay\fR option causes \fBgetch\fR to be a non-blocking call.
 If no input is ready, \fBgetch\fR returns \fBERR\fR.
 If disabled
 (\fIbf\fR is \fBFALSE\fR), \fBgetch\fR waits until a key is pressed.
+.SS notimeout
 .PP
-While interpreting an input escape sequence, \fBwgetch\fR(3X) sets a timer
+When interpreting an escape sequence, \fBwgetch\fR(3X) sets a timer
 while waiting for the next character.
 If \fBnotimeout(\fR\fIwin\fR,
 \fBTRUE\fR) is called, then \fBwgetch\fR does not set a timer.
@@ -221,11 +234,11 @@ The behavior of
 the BREAK key depends on other bits in the tty driver that are not set by
 \fBcurses\fR.
 .\"
-.SS noqiflush
+.SS qiflush/noqiflush
 .PP
 When the \fBnoqiflush\fR routine is used, normal flush of input and
 output queues associated with the \fBINTR\fR, \fBQUIT\fR and
-\fBSUSP\fR characters will not be done [see termio(7)].
+\fBSUSP\fR characters will not be done [see \fBtermios\fP(3)].
 When
 \fBqiflush\fR is called, the queues will be flushed when these control
 characters are read.
@@ -266,9 +279,10 @@ If \fIfd\fR is
 \-1, then no typeahead checking is done.
 .\"
 .SH RETURN VALUE
-All routines that return an integer return \fBERR\fR upon failure and OK (SVr4
-specifies only "an integer value other than \fBERR\fR") upon successful
-completion, unless otherwise noted in the preceding routine descriptions.
+All routines that return an integer return \fBERR\fR upon failure and \fBOK\fP
+(SVr4 specifies only \*(``an integer value other than \fBERR\fR\*('')
+upon successful completion,
+unless otherwise noted in the preceding routine descriptions.
 .PP
 X/Open does not define any error conditions.
 In this implementation,
@@ -290,21 +304,29 @@ initializes the terminal state.
 BSD curses differed from this slightly; it
 left the echo bit on at initialization, but the BSD \fBraw\fR call turned it
 off as a side-effect.
-For best portability, set echo or noecho explicitly
+For best portability, set \fBecho \fPor \fBnoecho\fP explicitly
 just after initialization, even if your program remains in cooked mode.
 .PP
+The XSI Curses standard is ambiguous on the question of whether \fBraw\fR
+should disable the CRLF translations controlled by \fBnl\fR and \fBnonl\fR.
+BSD curses did turn off these translations; AT&T curses (at least as late as
+SVr1) did not.
+We chose to do so, on the theory that a programmer requesting
+raw input wants a clean (ideally 8-bit clean) connection that the operating
+system will not alter.
+.PP
 When \fBkeypad\fP is first enabled,
 ncurses loads the key-definitions for the current terminal description.
 If the terminal description includes extended string capabilities,
 e.g., from using the \fB\-x\fP option of \fB@TIC@\fP,
 then ncurses also defines keys for the capabilities whose names
-begin with "k".
+begin with \*(``k\*(''.
 The corresponding keycodes are generated and (depending on previous
 loads of terminal descriptions) may differ from one execution of a
 program to the next.
 The generated keycodes are recognized by the \fBkeyname\fP function
-(which will then return a name beginning with "k" denoting the
-terminfo capability name rather than "K", used for curses key-names).
+(which will then return a name beginning with \*(``k\*('' denoting the
+terminfo capability name rather than \*(``K\*('', used for curses key-names).
 On the other hand, an application can use \fBdefine_key\fP to establish
 a specific keycode for a given string.
 This makes it possible for an application to check for an extended
@@ -329,13 +351,24 @@ and if a capability's value is the same as a previously-loaded
 key definition,
 the later definition is the one used.
 .SH NOTES
-Note that \fBecho\fR, \fBnoecho\fR, \fBhalfdelay\fR, \fBintrflush\fR,
-\fBmeta\fR, \fBnodelay\fR, \fBnotimeout\fR, \fBnoqiflush\fR,
-\fBqiflush\fR, \fBtimeout\fR, and \fBwtimeout\fR may be macros.
+Note that
+\fBecho\fR,
+\fBnoecho\fR,
+\fBhalfdelay\fR,
+\fBintrflush\fR,
+\fBmeta\fR,
+\fBnl\fR,
+\fBnonl\fR,
+\fBnodelay\fR,
+\fBnotimeout\fR,
+\fBnoqiflush\fR,
+\fBqiflush\fR,
+\fBtimeout\fR, and
+\fBwtimeout\fR may be macros.
 .PP
 The \fBnoraw\fR and \fBnocbreak\fR calls follow historical practice in that
-they attempt to restore to normal (`cooked') mode from raw and cbreak modes
-respectively.
+they attempt to restore to normal (\*(``cooked\*('') mode
+from raw and cbreak modes respectively.
 Mixing raw/noraw and cbreak/nocbreak calls leads to tty driver
 control states that are hard to predict or understand; it is not recommended.
 .SH SEE ALSO
@@ -344,4 +377,4 @@ control states that are hard to predict or understand; it is not recommended.
 \fBcurs_initscr\fR(3X),
 \fBcurs_util\fR(3X),
 \fBdefine_key\fR(3X),
-\fBtermio\fR(7)
+\fBtermios\fR(3)