Term::ReadKey#

📦 std

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#

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#

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

SetReadMode#

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

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#

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#

Tell a terminal its size.

GetSpeed#

A terminal’s input and output speeds in baud.

GetControlChars#

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

SetControlChars#

Change a terminal’s control characters.