Re: suspend-tty

[Stefan Monnier]

> Does anyone know what is the purpose of suspend-tty?  (Please don't
> tell "to stop I/O from/to a terminal", since that just repeats the
> name of the function.)  IOW, under what circumstances would a Lisp
> program want to do that, and what could be then done with the terminal
> which Emacs ``suspended''?

[ The blind leading the blind... ]

In the case of server.er, I believe it's used as follows:
When emacsclient receives a SIGSTOP (aka C-z), it sends a message to the
Emacs process, which then calls suspend-tty, which basically puts the
corresponding terminal object in a special state that prevents Emacs from
reading&writing to/from that tty.  Then the Emacs process sends
a message to emacsclient to suspend itself (so the shell from which it
was started is told that the suspend has taken place).

So suspend-tty just stops Emacs from using that tty (and tries to
restore its mode to default settings) so that some other application can
take control of it.

> I tried invoking suspend-tty on a GNU/Linux machine, and the terminal
> just got hang, the only thing I could do is abort Emacs.  (If I had
> another tty open in the same session, I understand I could resume-tty,
> but that doesn't really answers my question.)  I thought suspend-tty
> would leave the terminal free for use by other programs, but it sounds
> like I misunderstood?

It was probably free for use by other programs, but no other program was
told to use it.  E.g. the shell from which you started Emacs was not
told, so it was still waiting for Emacs to suspend itself or to exit.

> The only non-trivial user of suspend-tty is server.el, but the new
> functionality that uses it is completely undocumented, both in the
> code, in NEWS and in the manuals, and the semantics of using this API
> evaded me.

For me, the docstring seems to say "clearly" what the function does.
The name is slightly misleading, tho, because it applies to a terminal
rather than to a tty.  Of course, it only applies to terminals of tty
kind, but a given tty can have several terminals associated with it
(e.g. if you do "emacsclient -t; C-z; emacsclient -t").

So, do you understand what it does, now?  If so, how would you suggest
we change the docstring to make it more clear for you as well?


        Stefan