package matrix

Build not yet checked
  1. Overview
  2. Docs
Fast, modern terminal toolkit for OCaml

Install

dune-project
 Dependency

Authors

Maintainers

Sources

mosaic-0.3.0.tbz
sha256=a92cbbcbe016fb19fb0a749222da0e459a9567aef3f4c7340d9bd6b71c53ed6f
sha512=6a7ab054605538bb31a2b73a1a6d093981a2704c9f0af5852221c05735290d74aca7c7282298c4d0f91e86a800e2ccd94b4918af883cd963449c758eb6b272b3

doc/matrix.tty/Tty/Signal/index.html

Module Tty.SignalSource

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

A program that changes a terminal's settings or modes must put them back when a signal ends or stops the process. Otherwise the shell gets a terminal that echoes nothing, reports the mouse or shows no cursor. A process has one action per signal, which the program, the libraries it links and every holder share. This module takes the actions once, by one policy, and tells every holder of the signals that concern it.

The policy

  • SIGINT, SIGTERM, SIGHUP and SIGQUIT end the process, so they concern every holder, on any terminal. A system call they interrupt is not resumed, so a write the terminal is not taking returns and the holder can give its terminal back.
  • SIGABRT, which abort() raises, returns to no point where OCaml can run. Its handler restores every holder's terminal itself, as Signal.restore_all does, and the process aborts.
  • SIGTSTP, SIGWINCH and SIGCONT concern the holders of the controlling terminal (is_controlling) alone. Its job is the one the shell stops and continues, and its window the one that SIGWINCH reports. A terminal the process serves, such as a pseudo-terminal it opened, reports its size itself.

SIGINT, SIGTERM, SIGHUP, SIGQUIT, SIGABRT and SIGTSTP are taken only when their action is the default, as X/Open Curses allows, so a program that installed its own action keeps it and writes its own handler. SIGWINCH and SIGCONT are taken whatever their action, and a handler installed before them is still called. The system calls that SIGTSTP, SIGWINCH, SIGCONT and SIGABRT interrupt are resumed (SA_RESTART), so a resize never cuts a write. Signal.write goes on with a write that a signal cuts all the same.

Holders take a signal together. The first Signal.take installs the handler, and the action it replaced comes back when the last holder gives the signal back (Signal.give_back). The handlers are C. A handler records the signal for each holder it concerns and wakes the holder, by writing one byte to its wake pipe (Signal.wake_fd), so a holder waiting in Signal.wait wakes whenever the signal lands.

Signals are numbered as OCaml numbers them (Sys.sigint).

On Windows

Windows has SIGINT and SIGABRT alone. A console control handler, which C registers while a holder is active, receives Ctrl+C and Ctrl+Break as SIGINT when SIGINT's action is the default, and the console's closing as SIGHUP, always: the handler then waits while the holders give their terminals back and end the process, which Windows ends after 5 s whatever the handlers do. Ctrl+C reaches the handler only when the console turns it into a signal, outside raw mode. SIGABRT is taken as on POSIX. The other signals are never taken nor received, but SIGWINCH, which Signal.read receives when it reads a resize. Signal.ignored is false, Signal.stop_group does nothing, and Signal.raise_default ends the process as the console's own handler does, with STATUS_CONTROL_C_EXIT, and with no exit function run. A holder's wake is an event rather than a pipe.

Actions

Sourceval signals : controlling:bool -> int list

signals ~controlling is the signals a holder of a terminal takes. They are SIGABRT, SIGINT, SIGTERM, SIGHUP and SIGQUIT, and before them, when the terminal is the controlling one, SIGWINCH, SIGCONT and SIGTSTP.

Sourceval take : int -> bool

take s takes s as the policy says and is true iff it did. It is false when the program has an action of its own for s and the policy leaves s to it, and on Windows for the signals it lacks.

Raises Invalid_argument if s is not one of signals's.

Sourceval give_back : int -> unit

give_back s gives back a take s that was true. The action s had before comes back once every holder that took it has given it back.

Sourceval ignored : int -> bool

ignored s is true iff the action of s is to ignore it. Nothing would continue a job whose SIGTSTP is ignored once it stopped, so a holder does not stop such a job (stop_group).

Sourceval raise_default : int -> unit

raise_default s sets the action of s to the default, forgets every take of it, and raises it in the calling thread, so that the process ends or stops as it would with no handler. If the process stops, raise_default returns once it is continued, and s's action stays the default until it is taken again. A give_back of an earlier take of s then does nothing.

Sourceval stop_group : unit -> unit

stop_group () sends SIGTSTP to the process's group, as the terminal's suspend character does. Where SIGTSTP's action is the default, the job stops, the process with it, and stop_group returns once the job is continued.

Holders

A holder is valid from hold to release. Every function below that is given a holder after its release raises Invalid_argument, except wake, which then does nothing.

Sourcetype holder

The type for holders of a terminal.

Sourceval hold : controlling:bool -> output:Unix.file_descr option -> holder

hold ~controlling ~output registers a holder of a terminal, the controlling one if controlling, with a wake of its own. If the process ends where no OCaml code runs, the holder's reset bytes (set_reset) are written to output, the descriptor that the terminal is written through. It takes no signal (take does).

Raises Unix.Unix_error if the wake cannot be made, and Failure on a Windows older than Windows 10 1803, which has no high-resolution timer for wait.

Sourceval release : holder -> unit

release h ends h. The handlers forget it, and an abort no longer restores its terminal.

Sourceval wake_fd : holder -> Unix.file_descr

wake_fd h is the read end of h's wake pipe. It is non-blocking, and readable once a signal that concerns h has been received, or wake has been called, since the holder last read it empty or wait returned.

Raises Invalid_argument on Windows, where the wake is no descriptor.

Sourceval wake : holder -> unit

wake h wakes h: it ends the wait under way or the next one, and makes wake_fd readable. It may be called from any thread or domain, and does nothing once h is released, so a thread may wake a holder that another thread releases.

Sourceval wait : holder -> input:Unix.file_descr option -> until:int option -> bool

wait h ~input ~until waits until read has something to take from input, h is woken (wake, or a signal that concerns h), or now reaches until, and is true iff read has something to take. A wake that came since the last wait returned ends it at once. It waits for nothing but the wake and the time when input is None, and forever for those when until is None. A file is always readable.

On POSIX it is select(2) on input and the wake pipe. On Windows input is a console or a file, waited for with a high-resolution timer, and wait is true when the console holds records, which may carry no text.

Raises Invalid_argument on Windows if input is neither a console nor a file, such as a pipe, which Windows cannot wait for.

Sourceval read : holder -> Unix.file_descr -> bytes -> int -> int -> int

read h fd buf off len reads at most len bytes of what fd has into buf from off, without waiting once wait said there is something. It is the number of bytes read, 0 at the end of the input, and -1 when nothing is there, as for a non-blocking fd with nothing to read.

On a Windows console it reads the console's records and gives the text of the keys they carry as UTF-8, as the console's own reader would. Text that does not fit in len is kept for the next read. A resize is received for h as SIGWINCH (received) and wakes h. A read that took only records with no text is -1.

Raises Unix.Unix_error on an error other than EINTR and EAGAIN, and Invalid_argument if off and len are not a valid range of buf.

Sourceval received : holder -> int -> bool

received h s is true iff s has been received for h since h was made or since the last received h s.

Raises Invalid_argument if s is not a signal number of the system.

Sourceval terminating : holder -> bool

terminating h is true iff SIGINT, SIGTERM, SIGHUP or SIGQUIT has been received for h and not yet taken with received.

Sourceval keep_settings : holder -> input:Unix.file_descr -> unit

keep_settings h ~input saves the settings input has now, which are put back if the process ends where no OCaml code runs. It saves nothing if input is not a terminal.

Sourceval forget_settings : holder -> unit

forget_settings h drops the settings keep_settings saved, once the holder has put them back itself.

Sourceval set_reset : holder -> string -> unit

set_reset h bytes makes bytes h's reset bytes, the bytes that reset the modes h has set, of any length. They are written to h's output (hold) if the process ends where no OCaml code runs. A holder that has given its terminal back sets "". A handler that runs while set_reset replaces the bytes writes either the old bytes or the new ones whole.

A holder must set the bytes that depend on a write only after the write has returned. A signal that came in between would otherwise reset for a screen the terminal does not show.

Sourceval restore_all : unit -> unit

restore_all () restores the terminal of every holder not yet released, as an abort does. It writes each holder's reset bytes to its output and puts back the settings the holder kept. A holder that ends the process on a termination signal gives its own terminal back, then calls restore_all for the others, for which no OCaml code will run.

Sourceval write : holder -> Unix.file_descr -> bytes -> int -> int -> unit

write h fd buf off len writes the len bytes of buf from off to fd. It blocks until every byte is written. It goes on from where a write stopped when a signal cut it, and waits for fd to take more when fd is non-blocking and full. When a signal that ends the process (terminating) interrupts it, it returns with the rest unwritten.

Raises Unix.Unix_error on an error other than EINTR and EAGAIN.