curs\_inopts(3X) Library calls curs\_inopts(3X)

# [NAME](#NAME)

**cbreak**, **echo**, **halfdelay**, **intrflush**, **is\_cbreak**, **is\_echo**, **is\_nl**, **is\_raw**, **keypad**, **meta**, **nl**, **nocbreak**, **nodelay**, **noecho**, **nonl**, **noqiflush**, **noraw**, **notimeout**, **qiflush**, **raw**, **timeout**, **wtimeout**, **typeahead** - get and set *curses* terminal input options

# [SYNOPSIS](#SYNOPSIS)

```
#include <curses.h>
```

```
int cbreak(void);
int nocbreak(void);
```

```
int echo(void);
int noecho(void);
```

```
int intrflush(WINDOW * win /* ignored */, bool bf);
int keypad(WINDOW * win, bool bf);
int meta(WINDOW * win /* ignored */, bool bf);
int nodelay(WINDOW * win, bool bf);
int notimeout(WINDOW * win, bool bf);
```

```
int nl(void);
int nonl(void);
```

```
void qiflush(void);
void noqiflush(void);
```

```
int raw(void);
int noraw(void);
```

```
int halfdelay(int tenths);
void timeout(int delay);
void wtimeout(WINDOW * win, int delay);
```

```
int typeahead(int fd);
```

```
/* extensions */
int is_cbreak(void);
int is_echo(void);
int is_nl(void);
int is_raw(void);
```

# [DESCRIPTION](#DESCRIPTION)

*curses* offers configurable parameters permitting an application to control the handling of input from the terminal. Some, such as those affecting the terminal's *mode* or line discipline, are global, applying to all windows; others apply only to a specific window. The library does not automatically apply such parameters to new or derived windows; an application must configure each window for the desired behavior.

Some descriptions below make reference to an *input character reading function*: this is [**wgetch**(3X)](/man/os/ncurses/wgetch.3X) in the non-wide character *curses* API and [**wget\_wch**(3X)](/man/os/ncurses/wget_wch.3X) in the wide character API. In addition to the variant forms of these described in [**ncurses**(3X)](/man/os/ncurses/ncurses.3X), the *curses* functions [**wgetstr**(3X)](/man/os/ncurses/wgetstr.3X) and [**wget\_wstr**(3X)](/man/os/ncurses/wget_wstr.3X) and their own variants call the appropriate input character reading function.

## [cbreak, nocbreak](#cbreak,_nocbreak)

Normally, the terminal driver buffers typed characters, not delivering them to an application until a line feed or carriage return is typed. This canonical (“cooked”) line discipline also supports software flow control, simple line editing functions (character and word erase, and whole-line erasure or “kill”), and job control. **cbreak** configures the terminal in *cbreak mode*, which disables line buffering and erase and kill character processing — the interrupt, quit, suspend, and flow control characters are unaffected — and makes characters typed by the user immediately available to the program. **nocbreak** restores canonical (“cooked”) mode.

The state of the terminal is unknown to a *curses* application when it starts; therefore, a program should call **cbreak** or **nocbreak** explicitly. Most interactive programs using *curses* set cbreak mode. Calling **cbreak** overrides **raw**. The man page for the input character reading function discusses how **cbreak** and **nocbreak** interact with **echo** and **noecho**.

## [echo, noecho](#echo,_noecho)

**echo** and **noecho** determine whether characters typed by the user are written to the *curses* window by the input character reading function as they are typed. *curses* always disables the terminal driver's own echoing. By default, a *curses* screen's echo option is set. Authors of most interactive programs prefer to do their own echoing in a controlled area of the screen, or not to echo at all, so they call **noecho**. The man page for the input character reading function discusses how **echo** and **noecho** interact with **cbreak** and **nocbreak**.

## [halfdelay](#halfdelay)

**halfdelay** configures *half-delay mode*, which is similar to cbreak mode in that characters typed by the user are immediately available to the program. However, after blocking for *tenths* tenth-seconds, an input character reading function returns **ERR** if no input is pending. The value of *tenths* must be between 1 and 255. Use **nocbreak** to leave half-delay mode.

## [intrflush](#intrflush)

**intrflush** calls **qiflush** (see below) if *bf* is **TRUE**, and **noqiflush** if *bf* is **FALSE**. It ignores its *win* argument.

## [keypad](#keypad)

**keypad** enables recognition of a terminal's function keys. If enabled (*bf* is **TRUE**) then when an input character reading function reads a character that is a common prefix to multiple key-defining string capabilities (typically ESC), it waits for further input corresponding to an escape sequence defined by the terminal type description. If a valid sequence populates the input stream, the input character reading function returns a value representing the function key, such as **KEY\_LEFT**. (Wide-character API users: [**wget\_wch**(3X)](/man/os/ncurses/wget_wch.3X) returns **KEY\_CODE\_YES** to indicate the availability of a function key code in its *wch* parameter.) If the sequence is invalid, the input character reading function returns only its last character. If disabled (*bf* is **FALSE**), *curses* does not treat function keys specially; the application must itself interpret any character sequences they transmit. If the terminal type description defines the **keypad\_local** (**rmkx**) and **keypad\_xmit** (**smkx**) capabilities, enabling a window's keypad mode sets the terminal's keypad to transmit, and disabling keypad mode sets the terminal's keypad to work locally. By default, a window's keypad mode is off.

## [meta](#meta)

Initially, whether the terminal returns 7- or 8-bit character codes on input depends on the configuration of the terminal driver; on POSIX systems, see [*termios*(3)](/man/os/ncurses/termios.3). To force 8 bits to be returned, call **meta(**...**,** **TRUE)**; this is equivalent, on POSIX systems, to setting the CS8 flag on the terminal. To force 7 bits to be returned, call **meta(**...**,** **FALSE)**; this is equivalent, on POSIX systems, to setting the CS7 flag on the terminal. *curses* ignores the window argument *win*. If the *terminfo* string capabilities **meta\_on** (**smm**) and **meta\_off** (**rmm**) are defined for the terminal type, enabling meta mode sends **smm**'s value to the terminal and disabling it sends that of **rmm** to the terminal.

## [nl, nonl](#nl,_nonl)

Initially, whether the terminal reports a carriage return using the character code for a line feed in cbreak or raw modes depends on the configuration of the terminal driver; on POSIX systems, see [*termios*(3)](/man/os/ncurses/termios.3). **nl** configures the terminal to perform this translation. **nonl** disables it. Under its canonical (“cooked”) line discipline, the terminal driver always translates carriage returns to line feeds.

## [nodelay](#nodelay)

**nodelay** configures the input character reading function to be non-blocking for window *win*. If no input is ready, the reading function returns **ERR**. If disabled (*bf* is **FALSE**), the reading function does not return until it has input.

## [notimeout](#notimeout)

When **keypad** has been called on a window and the input character reading function reads an ambiguous prefix character (typically ESC) from it, *curses* sets a timer while waiting for the next character. If the timer elapses, *curses* interprets the prefix as an explicit press of the key corresponding thereto, such as Escape for ESC. **notimeout(win,** **TRUE)** disables this timer. The purpose of the timeout is to distinguish sequences produced by a function key from those typed by a user. If this timer is disabled, *curses* waits forever for subsequent keystrokes until it determines the escape sequence to be valid or invalid.

## [qiflush, noqiflush](#qiflush,_noqiflush)

**qiflush** and **noqiflush** configure the terminal driver's treatment of its input and output queues when it handles the interrupt, suspend, or quit characters under the canonical (“cooked”) or cbreak line disciplines on POSIX systems; see [*termios*(3)](/man/os/ncurses/termios.3). The default behavior is inherited from the terminal driver settings. Calling **qiflush** configures the terminal to *flush* the queues (discarding their contents) when any of these events occurs, giving the impression of faster response to user input, but making the library's model of the screen contents incorrect. Calling **noqiflush** prevents such flushing, but might frustrate impatient users on slow connections if a *curses* update of the screen is in progress when the event occurs; see **typeahead** below for a mitigation of this problem. You may want to call **noqiflush** in a signal handler if, after the handler exits, you want output to continue as though the signal had not occurred.

## [raw, noraw](#raw,_noraw)

**raw** configures the terminal to read input in *raw mode*, which is similar to cbreak mode (see **cbreak** above) except that it furthermore passes through the terminal's configured interrupt, quit, suspend, and flow control characters uninterpreted to the application, instead of generating a signal or acting on I/O flow. The behavior of the terminal's “Break” key (if any) depends on terminal driver configuration parameters that *curses* does not handle. **noraw** restores the terminal's canonical (“cooked”) line discipline.

## [timeout, wtimeout](#timeout,_wtimeout)

**wtimeout** configures whether a *curses* input character reading function called on window *win* uses blocking or non-blocking reads. If *delay* is negative, *curses* uses a blocking read, waiting indefinitely for input. If *delay* is zero, the read is non-blocking; an input character reading function returns **ERR** if no input is pending. If *delay* is positive, an input character reading function blocks for *delay* milliseconds, and returns **ERR** if the delay elapses and there is still no input pending. **timeout** calls **wtimeout** on **stdscr**.

## [typeahead](#typeahead)

Normally, a *curses* library checks the terminal's input file descriptor for activity with [*poll*(2)](/man/os/ncurses/poll.2) or [*select*(2)](/man/os/ncurses/select.2) while updating the screen; if it finds any, it postpones output until the next [**wrefresh**(3X)](/man/os/ncurses/wrefresh.3X) or [**doupdate**(3X)](/man/os/ncurses/doupdate.3X) call, allowing faster response to user key strokes. The library tests the file descriptor corresponding to the *FILE* stream pointer passed to [**newterm**(3X)](/man/os/ncurses/newterm.3X) (or *stdin* if [**initscr**(3X)](/man/os/ncurses/initscr.3X) was called), for pending input. **typeahead** instructs *curses* to test file descriptor *fd* instead. An *fd* of **-1** disables the check.

# [RETURN VALUE](#RETURN_VALUE)

**timeout** and **wtimeout** return no value.

**cbreak**, **nocbreak**, **echo**, **noecho**, **halfdelay**, **intrflush**, **keypad**, **meta**, **nodelay**, **notimeout**, **nl**, **nonl**, **raw**, **noraw**, and **typeahead** return **OK** on success and **ERR** on failure.

In *ncurses*, the functions in the previous paragraph return **ERR** if

- the library's *TERMINAL* structure for the device has not been initialized with [**initscr**(3X)](/man/os/ncurses/initscr.3X), [**newterm**(3X)](/man/os/ncurses/newterm.3X), or [**setupterm**(3X)](/man/os/ncurses/setupterm.3X), or
- *win* is a null pointer (except with **intrflush** and **meta**, which ignore its value).

Further, **halfdelay** returns **ERR** if *delay* is outside the range 1..255.

See section “EXTENSIONS” below for the return values of **is\_cbreak**, **is\_echo**, **is\_nl**, and **is\_raw**.

# [NOTES](#NOTES)

**echo**, **noecho**, **halfdelay**, **intrflush**, **meta**, **nl**, **nonl**, **nodelay**, **notimeout**, **noqiflush**, **qiflush**, **timeout**, and **wtimeout** may be implemented as macros.

**noraw** and **nocbreak** follow historical practice in that they attempt to restore the terminal's canonical (“cooked”) line discipline from raw and cbreak, respectively. Mixing **raw**/**noraw** calls with **cbreak**/**nocbreak** calls leads to terminal driver control states that are hard to predict or understand; doing so is not recommended.

*curses* documentation uses the terms “delay” and “timeout” freely to describe two related but distinct aspects of input handling, at the risk of confusing the user. The functions **halfdelay**, **nodelay**, **timeout**, and **wtimeout** configure whether the input character reading function ([**wgetch**(3X)](/man/os/ncurses/wgetch.3X) or [**wget\_wch**(3X)](/man/os/ncurses/wget_wch.3X)) waits for keyboard input to begin, and for how long. **keypad** configures whether that function waits for further input if the first character it reads is an ambiguous prefix (like ESC). Calling **notimeout**, which has nothing to do with **timeout** or **wtimeout**, makes this delay in expectation of further characters effectively infinite. X/Open Curses affords no means of otherwise configuring the length of this second delay, but an AIX and *ncurses* extension, **ESCDELAY**, is available both as an environment variable and a global symbol permitting the user and application, respectively, to do so; see [**ncurses**(3X)](/man/os/ncurses/ncurses.3X) and [**curs\_variables**(3X)](/man/os/ncurses/curs_variables.3X).

When **keypad** is first enabled for a window, *ncurses* loads the standard function key string capabilities for the terminal type description of its screen; see the table entries containing “key\_” in [**terminfo**(5)](/man/os/ncurses/terminfo.5). If that description includes extended string capabilities (produced by the **-x** option of [**tic**(1)](/man/os/ncurses/tic.1), for example), then for each extended function key whose capability code begins with “k”, *ncurses* generates a numeric key code. These code values are affected by previous loads of terminal type descriptions, and may differ from one execution of the application to the next. In *ncurses*, [**keyname**(3X)](/man/os/ncurses/keyname.3X) recognizes these generated key codes and returns a name beginning with “k” denoting the extended *terminfo* capability code rather than one starting with “KEY\_”, which standard *curses* key names use. Further, an application can use [**define\_key**(3X)](/man/os/ncurses/define_key.3X) to bind any key code to a string of the programmer's choice. This feature enables an application to check for a function key's presence with [**tigetstr**(3X)](/man/os/ncurses/tigetstr.3X), and reassign the key code to match its own needs.

Applications employing the lower-level *terminfo* API can use [**tigetstr**(3X)](/man/os/ncurses/tigetstr.3X) to obtain the contents of any string capability, including extended ones. Applications employing the higher-level *curses* API use an input character reading function to obtain key codes from input; the result can vary depending upon the order in which string capabilities are loaded. Multiple key capability strings can have the same value, but the input character reading function can report only one key code. Most *curses* implementations (including *ncurses*) load key definitions in the order they appear in the **strfnames** array of string capability names; see [**term\_variables**(3X)](/man/os/ncurses/term_variables.3X). The *last* capability read using a particular definition determines the key code to be reported. *ncurses* loads extended capabilities after standard ones. Thus, if an extended string capability's value is the same as one previously loaded, the input character reading function returns the last matching extended one.

# [EXTENSIONS](#EXTENSIONS)

*ncurses* provides four “is\_” functions corresponding to **cbreak**, **echo**, **nl**, and **raw**, permitting their states to be queried by the application.

**Query** **Set** **Reset** is\_cbreak cbreak nocbreak is\_echo echo noecho is\_nl nl nonl is\_raw raw noraw

In each case, the function returns

**1**

if the option is set,

**0**

if the option is unset, or

**-1**

if the library's *TERMINAL* structure for the device has not been initialized.

# [PORTABILITY](#PORTABILITY)

Applications employing *ncurses* extensions should condition their use on the visibility of the **NCURSES\_VERSION** preprocessor macro.

Except as noted in section “EXTENSIONS” above, X/Open Curses Issue 4 describes these functions. It specifies no error conditions for them.

SVr4 describes a successful return value only as “an integer value other than *ERR*”.

*ncurses* follows X/Open Curses and the historical practice of System V *curses*, clearing the terminal driver's “echo” flag when initializing the screen. BSD *curses* did not, but its *raw* function turned it off as a side effect. For best portability, call *echo* or *noecho* explicitly just after initialization, even if your program retains the terminal's canonical (“cooked”) line discipline.

X/Open Curses is ambiguous regarding whether *raw* should disable the carriage return and line feed translation feature controlled by *nl* and *nonl*. BSD *curses* turned off these translations; System V *curses* did not. *ncurses* does so, on the assumption that a programmer requesting raw input wants a clean (ideally, 8-bit clean) connection that the operating system does not alter.

# [HISTORY](#HISTORY)

4BSD (1980) introduced *echo*, *noecho*, *nl*, *nonl*, *raw*, and *noraw*.

SVr2 (1984) featured a new terminal driver, extending the *curses* API to support it with *cbreak*, *nocbreak*, *intrflush*, *keypad*, *meta*, *nodelay*, and *typeahead*.

SVr3 (1987) added *halfdelay*, *notimeout*, and *wtimeout*. *qiflush* and *noqiflush* appeared in SVr3.1 (1987), at which point *intrflush* became a wrapper for either of these functions, depending on the value of its Boolean argument. SVr3.1 also added *timeout*.

*ncurses* 6.5 (2024) introduced *is\_cbreak*, *is\_echo*, *is\_nl*, and *is\_raw*.

Formerly, *ncurses* used *nl* and *nonl* to control the conversion of newlines to carriage return/line feed on output as well as input. X/Open Curses documents the use of these functions only for input. This difference arose from converting the *pcurses* source (1986), which used [*ioctl*(2)](/man/os/ncurses/ioctl.2) calls and the *sgttyb* structure, to *termios* (the POSIX terminal API). In the former, both input and output conversions were controlled via a single option “CRMOD”, while the latter separates these features. Because that conversion interferes with output optimization, *ncurses* 6.2 (2020) amended *nl* and *nonl* to eliminate their effect on output.

# [SEE ALSO](#SEE_ALSO)

[**curses**(3X)](/man/os/ncurses/curses.3X), [**curs\_getch**(3X)](/man/os/ncurses/curs_getch.3X), [**curs\_initscr**(3X)](/man/os/ncurses/curs_initscr.3X), [**curs\_util**(3X)](/man/os/ncurses/curs_util.3X), [**define\_key**(3X)](/man/os/ncurses/define_key.3X), [**termios**(3)](/man/os/ncurses/termios.3), [**term\_variables**(3X)](/man/os/ncurses/term_variables.3X)

2026-09-19 ncurses 6.6

---

Document: is_raw(3x) from ncurses 6.6.20261031-r0 (Chainguard OS)
Source: https://github.com/ThomasDickey/ncurses-snapshots