package matrix

  1. Overview
  2. Docs

Module TtySource

The terminal device, as the operating system knows it.

A terminal is a file descriptor that the system drives as one (isatty(3)), such as a console, a serial line or either side of a pseudo-terminal. The system keeps three things for a terminal, which this module reads and sets. They are the size of its window (window), the settings of its line discipline, the part of the system that edits what is typed before a program reads it (Settings), and the signals it sends the process (Signal). The module also finds the description of a terminal type in the terminfo database (terminfo) and has the monotonic clock (now) by which the libraries above it time a terminal's answers. What to write to a terminal is decided above this library, by Matrix_terminal and Ansi.

A program that takes a terminal for itself, as a full-screen program does, goes through these steps and undoes them in reverse order:

  1. is_tty and is_controlling tell what its descriptors are.
  2. Signal.hold registers the program as a holder of the terminal, and Signal.take takes each of Signal.signals.
  3. Signal.keep_settings keeps the terminal's settings for an abort, and raw turns the line discipline off and returns the same settings.
  4. While it runs, it reads window again after each SIGWINCH that Signal.received reports.
  5. restore puts the settings back, Signal.give_back gives back each signal it took, and Signal.release ends the holder.

This reads one key as it is typed, with no echo and no Enter, and puts the settings back however the read ends:

let () =
  let saved = Tty.raw Unix.stdin in
  Fun.protect ~finally:(fun () -> Tty.restore Unix.stdin saved) @@ fun () ->
  let key = Bytes.create 1 in
  ignore (Unix.read Unix.stdin key 0 1 : int)

The device

Sourceval is_tty : Unix.file_descr -> bool

is_tty fd is true iff fd is a terminal (isatty(3)). It is false for a closed descriptor.

Sourceval is_controlling : Unix.file_descr -> bool

is_controlling fd is true iff fd is the process's controlling terminal, the terminal associated with the process's session (tcgetsid(3)), whose job the process runs in. The shell stops and continues the job through it, and its window is the one SIGWINCH reports. The master side of a pseudo-terminal is false, even when its slave is the controlling terminal. So is a pseudo-terminal the process opened. On Windows, where a process has at most one console and receives its control events, it is true iff fd is a handle of the process's console.

Sourceval background : Unix.file_descr -> bool

background fd is true iff fd is the process's controlling terminal and the process's group is not its foreground group (tcgetpgrp(3)), the group of the job the shell lets read the terminal. A shell with job control runs a job in the background after & or bg. A write from the background goes through, unless the terminal's TOSTOP setting is on and stops the process (SIGTTOU), so it lands among what the shell and the job in the foreground write. It is false on Windows.

Sourceval window : Unix.file_descr -> (int * int) option

window fd is the size of fd's window, Some (cols, rows), as the system reports it (TIOCGWINSZ, or the window of the console screen buffer on Windows). It is None when fd is not a terminal or the system reports a zero size, as it does for a pseudo-terminal whose size was never set.

Sourceval window_pixels : Unix.file_descr -> (int * int) option

window_pixels fd is the size of fd's window in pixels, Some (width, height), as the system reports it (TIOCGWINSZ). It is None when fd is not a terminal, when the system reports a zero size, as many terminals and every pseudo-terminal whose pixel size was never set do, and on Windows.

Sourceval readable : Unix.file_descr -> bool

readable fd is true iff a read from fd would return without waiting: fd has input, has reached its end, or has an error to report. It never waits (poll(2) with no timeout), takes nothing from fd and allocates nothing. On Windows a console's handle is asked whether it is signaled, which takes none of the records it holds, as waiting with Unix.select does. A console is signaled while it holds records, which may carry no text, such as a resize: Signal.read may then have nothing to give.

Sourceval now : unit -> int

now () is the time in nanoseconds since an arbitrary origin, on a clock that never goes back and that setting the system's time does not move (CLOCK_MONOTONIC, or the performance counter on Windows). On Linux the clock stops while the system sleeps, so a deadline comes that much later on the wall clock. On macOS it goes on while the system sleeps.

Settings

A terminal's line discipline echoes what is typed, collects a line until Enter, and turns the interrupt, quit and suspend characters into signals. A program that reads every key as it is typed turns all of that off with raw. One that reads keys and leaves the signals to the terminal, as a prompt does, turns off the echo and the lines with keys, and one that reads a password turns off the echo alone with no_echo. Each returns the settings it replaced, and restore puts them back.

Sourcetype settings

The type for a terminal's settings, what tcgetattr(3) gives, with the IEXTEN local flag that Unix.terminal_io leaves out. On Windows they are a console's input mode.

raw fd puts fd in raw mode immediately and returns the settings it had. In raw mode the terminal does not echo, edits no line, and turns no character into a signal, so Ctrl+C reaches the program as a byte. It also turns off output flow control (IXON) and the implementation-defined input characters (IEXTEN), with which the system would keep ^O and ^V, and stops turning CR into LF (ICRNL). A read returns as soon as one byte is there. Output processing (OPOST) and the file status flags, such as O_NONBLOCK, stay as they were.

On Windows fd is a console, which then neither echoes, edits lines nor turns Ctrl+C into a signal, and gives keys, mouse reports, pastes and focus changes as the control functions a VT100-style terminal sends (ENABLE_VIRTUAL_TERMINAL_INPUT). It reports resizes, and a click reaches the program instead of starting a selection, where the console's mode says what its quick edit was. Read it with Signal.read, which takes those records as the bytes they carry.

Raises Unix.Unix_error if fd is not a terminal, and Failure if the Windows console takes no virtual terminal input.

keys fd puts fd in the key interval immediately and returns the settings it had. The terminal echoes nothing and edits no line, so a read returns each key as soon as one byte of it is there, and a carriage return stays one (ICRNL is off), as it is in raw mode. The interrupt, quit and suspend characters still send their signals to the job (ISIG), the implementation-defined characters stay (IEXTEN), and output is processed as before. So Ctrl+C ends the job and Ctrl+Z stops it as at a shell's prompt, while Ctrl+D, the erase and the kill characters reach the program as bytes. Input not yet read stays. On Windows the console gives keys as in raw mode, and Ctrl+C still sends its signal.

Raises Unix.Unix_error if fd is not a terminal, and Failure if the Windows console takes no virtual terminal input.

no_echo fd turns fd's echo off and returns the settings it had, as getpass(3) does to read a password. Lines are still edited, the signal characters still send their signals, and nothing typed is shown, line end included (ECHO, ECHOE, ECHOK and ECHONL are off). It first discards the input not yet read (TCSAFLUSH), so what was typed before the question is not taken as its answer. A Windows console's input stays.

Raises Unix.Unix_error if fd is not a terminal.

Sourceval restore : Unix.file_descr -> settings -> unit

restore fd s sets fd's settings to s and keeps the input not yet read for whoever reads next. It blocks until the output written to fd has been sent (TCSADRAIN). SIGTTOU is blocked in the calling thread meanwhile, so that a process in the background sets the settings instead of stopping.

Raises Unix.Unix_error if fd is not a terminal.

Sourceval flush_input : Unix.file_descr -> unit

flush_input fd discards the input fd has received and nobody has read (tcflush, TCIFLUSH, or the records of a Windows console). It does nothing if fd is not a terminal.

Sourcetype console

The type for what enable_vt changes in a Windows console, the mode of the console and the output code page of the process's console.

Sourceval enable_vt : Unix.file_descr -> console

enable_vt fd has the Windows console fd interpret the control functions written to it as a VT100 does, sets the output code page of the process's console to UTF-8, and returns the mode and code page it replaced. The console also defers the wrap (DISABLE_NEWLINE_AUTO_RETURN). A character written in the last column leaves the cursor there, and the cursor moves to the next line only when the next printable character comes, so a line that fills the width and ends with a line feed takes one row. The console is shared by every process attached to it, the shell among them, so a program must give the result to restore_console before it ends. If the process ends on a signal that a holder received (Signal.raise_default), or aborts, the consoles not given back get their mode and code page back, the last changed first. It does nothing on other systems, or if fd is not a console.

Raises Failure if 16 consoles changed are not given back.

Sourceval restore_console : Unix.file_descr -> console -> unit

restore_console fd c sets the mode of the console fd and the output code page of the process's console back to those c holds. It does nothing when the enable_vt that returned c did nothing.

Terminal descriptions

The description of a terminal type name is looked for in these places, in order, as ncurses looks for it (terminfo(5), "Fetching Compiled Descriptions"):

  1. TERMINFO, which is a database, or a description itself encoded in hexadecimal after hex: or in base64 after b64: (as tic -Q writes them), used only if one of its names is name;
  2. $HOME/.terminfo;
  3. each database of TERMINFO_DIRS, separated by colons, where an empty one is /usr/share/terminfo;
  4. the system's databases, /etc/terminfo, /lib/terminfo, /usr/share/terminfo, /usr/lib/terminfo, /usr/share/lib/terminfo and /usr/local/share/terminfo.

In a database, the description is the file name in the directory named by name's first character, or by that character's code in two hexadecimal digits, as a database on a file system that ignores case has it. A database kept as a hashed file is not read. An empty variable counts as unset. A process whose user or group differs from its caller's (setuid) reads none of TERMINFO, HOME and TERMINFO_DIRS, so that its caller cannot give it a description.

Sourceval terminfo : string -> (Matrix_terminfo.t, [ `Not_found | `Invalid of string ]) result

terminfo name is the first description of the terminal type name, such as TERM's value, that reads (Matrix_terminfo.of_string) in the places the section lists. It is Error (`Invalid why) when descriptions were found and none reads, where why says why the first one does not. It is Error `Not_found when there is none, and when name cannot be a file name ("", ".", "..", or a name with a /).

Signals

Sourcemodule Signal : sig ... end

The signals a terminal sends the process, shared by every holder of a terminal in it.