<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from Term/ReadKey.rs. Do not edit. -->

```{index} single: Term::ReadKey
```

# Term::ReadKey

```{pperl-module-badges} Term::ReadKey
```

Terminal modes (cooked, no-echo, cbreak, raw), reads that time out or
do not block, and the terminal's size, speed and control characters.


## Synopsis

```perl
use Term::ReadKey;

ReadMode 'cbreak';                  # one key at a time, no echo
my $key = ReadKey(0.5);             # wait half a second at most
ReadMode 'restore';

my ($cols, $rows) = GetTerminalSize();
my %cc = GetControlChars();         # INTERRUPT => "\cC", ...
```

## How it works

`ReadMode` changes the handle's termios settings, saving the ones it
found on first use; mode 0 (`restore`) puts those back and forgets
them. `ReadKey` and `ReadLine` with a positive timeout wait with
`select()`, and with a negative one switch the handle to non-blocking
for the one read. `GetTerminalSize` asks the terminal (TIOCGWINSZ),
then `$COLUMNS`/`$LINES`, then `resize` and `stty size`.

This is a native implementation of TermReadKey 2.38's `ReadKey.xs`
and the `cchars.h` its genchars.pl writes, as they build on Linux
(termios, `O_NDELAY` and `select()`, no `poll()`); its
`Term/ReadKey.pm`, which ReadKey.pm.PL writes, is used unchanged.

## Differences from upstream

Three, each where perl 5.44 with ReadKey.xs aborts or returns memory
it never wrote (t/81-xs-native/Term-ReadKey/150-or-better.t):

- A timed `ReadKey`/`ReadLine` on a closed handle reads nothing, as
  an untimed one does; perl5 aborts ("bit out of range 0 - FD_SETSIZE
  on fd_set"). One on a descriptor of 1024 or above waits as on any
  other; perl5 aborts the same way.
- `GetSpeed` on a handle that is not a terminal returns (0, 0); perl5
  returns two numbers from uninitialised memory, different each time.
- `SetTerminalSize` with a width or height of ten characters or more
  (1000000000, -100000000) sets `COLUMNS`/`LINES` for child processes
  as for any other; perl5 aborts ("buffer overflow detected").

## Functions

### Terminal modes

#### [`selectfile`](ReadKey/selectfile)

Wait until a handle has input, for at most `delay` seconds.

#### [`SetReadMode`](ReadKey/SetReadMode)

Put a terminal handle into one of the modes 0 to 5.

#### [`setnodelay`](ReadKey/setnodelay)

Switch a handle's descriptor to non-blocking reads (`mode` true) or back.

#### `pollfile`

The `poll()` wait of builds that have it; this one dies "pollfile is not supported on this architecture".

#### `Win32PeekChar`

The Windows console read; here it dies "Win32PeekChar is not supported on this architecture".

### Terminal properties

#### `blockoptions`

The ways this build can read without blocking, as bits: 1 non-blocking descriptors, 2 `poll()`, 4 `select()`, 8 the Windows console. Here 5.

#### `termoptions`

The terminal interface this build drives: 1 termios, 2 termio, 3 sgtty, 4 the `stty` program, 5 the Windows console. Here 1.

#### `termsizeoptions`

The ways this build can ask a terminal its size, as bits: 1 OS/2's VIO, 2 TIOCGWINSZ, 4 TIOCGSIZE, 8 the Windows console. Here 2.

#### `GetTermSizeWin32`

The Windows console's size; here it dies "TermSizeWin32 is not implemented on this architecture".

#### `GetTermSizeVIO`

OS/2's screen size; here it dies "TermSizeVIO is not implemented on this architecture".

#### [`GetTermSizeGWINSZ`](ReadKey/GetTermSizeGWINSZ)

A terminal's size from the TIOCGWINSZ ioctl.

#### `GetTermSizeGSIZE`

The TIOCGSIZE size of systems without TIOCGWINSZ; here it dies "TermSizeGSIZE is not implemented on this architecture".

#### [`SetTerminalSize`](ReadKey/SetTerminalSize)

Tell a terminal its size.

#### [`GetSpeed`](ReadKey/GetSpeed)

A terminal's input and output speeds in baud.

#### [`GetControlChars`](ReadKey/GetControlChars)

A terminal's control characters, as name/character pairs.

#### [`SetControlChars`](ReadKey/SetControlChars)

Change a terminal's control characters.

```{toctree}
:hidden:
:maxdepth: 1

ReadKey/selectfile
ReadKey/SetReadMode
ReadKey/setnodelay
ReadKey/GetTermSizeGWINSZ
ReadKey/SetTerminalSize
ReadKey/GetSpeed
ReadKey/GetControlChars
ReadKey/SetControlChars
```