X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_inopts.3x;h=d346017ba0ea09dba6a0e38648c06578bf23a186;hp=c1882eaefd99023ae84f671e14b5d3d345f78127;hb=152c5a605234b7ea36ba3a03ec07e124bb6aac75;hpb=ce4803687b821efbc5fb2c5a5f06d69cd4dc2656;ds=sidebyside diff --git a/man/curs_inopts.3x b/man/curs_inopts.3x index c1882eae..d346017b 100644 --- a/man/curs_inopts.3x +++ b/man/curs_inopts.3x @@ -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.25 2017/02/18 16:39:44 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 `` `` @@ -43,12 +44,14 @@ \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 @@ -60,36 +63,40 @@ \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,9 +304,17 @@ 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, @@ -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)