package matrix
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, asSignal.restore_alldoes, 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
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.
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.
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).
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.
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.
The type for holders of a terminal.
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.
release h ends h. The handlers forget it, and an abort no longer restores its terminal.
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.
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.
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.
terminating h is true iff SIGINT, SIGTERM, SIGHUP or SIGQUIT has been received for h and not yet taken with received.
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.
forget_settings h drops the settings keep_settings saved, once the holder has put them back itself.
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.
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.
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.