(Suspending Emacs): Update for multi-tty; document `suspend-tty',

`resume-tty', and `controlling-tty-p'.

1 files changed, 53 insertions, 0 deletions

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index e0ffbd16c2e..94bb023abc5 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -577,6 +577,11 @@ same buffers, the same kill ring, the same undo history, and so on.  To
 resume Emacs, use the appropriate command in the parent shell---most
 likely @code{fg}.
 
+@cindex controlling terminal
+  Suspending works only on a terminal device from which the Emacs
+session was started.  We call that device the @dfn{controlling
+terminal} of the session.
+
   Some operating systems do not support suspension of jobs; on these
 systems, ``suspension'' actually creates a new shell temporarily as a
 subprocess of Emacs.  Then you would exit the shell to return to Emacs.
@@ -592,6 +597,13 @@ This function stops Emacs and returns control to the superior process.
 If and when the superior process resumes Emacs, @code{suspend-emacs}
 returns @code{nil} to its caller in Lisp.
 
+This function works only on the controlling terminal of the Emacs
+session; to relinquish control of other tty devices, use
+@code{suspend-tty} (@pxref{Visibility of Frames}).  If the Emacs
+session uses more than one terminal device, you will need to delete
+the frames on all the other devices before suspending Emacs, otherwise
+this function signals an error.
+
 If @var{string} is non-@code{nil}, its characters are sent to be read
 as terminal input by Emacs's superior shell.  The characters in
 @var{string} are not echoed by the superior shell; only the results
@@ -663,6 +675,47 @@ This variable is a normal hook that Emacs runs on resuming
 after a suspension.
 @end defvar
 
+@defun suspend-tty &optional tty
+If @var{tty} specifies a terminal device used by Emacs, this function
+relinquishes the device and restores it to its prior state.  Frames
+that used the device continue to exist, but are not updated and Emacs
+doesn't read input from them.  If @var{tty} is a frame, it means that
+frame's terminal; if it is @code{nil}, the function uses the selected
+frame's terminal.  If @var{tty} is already suspended, the function
+does nothing.
+
+This function runs the hook @code{suspend-tty-functions} (each
+function gets one argument, the terminal that corresponds to
+@var{tty}).
+@end defun
+
+@defun resume-tty &optional tty
+Resume the previously suspended terminal device @var{tty}.  If
+@var{tty} is a frame, it means resume that frame's terminal;
+@code{nil} means the selected frame.
+
+This function reopens the terminal device, re-initializes it, and
+redraws its with that terminal's selected frame.  It then runs the
+hook @code{resume-tty-functions}, passing each function the terminal
+which corresponds to @var{tty}.
+
+If the same device is already used by another Emacs terminal, this
+function signals an error.
+@end defun
+
+@defun controlling-tty-p &optional terminal
+This function returns non-@code{nil} if @var{terminal} is the
+controlling terminal device of the Emacs session.
+@end defun
+
+@deffn Command suspend-frame
+This command @dfn{suspends} a frame.  For GUI frames, it calls
+@code{iconify-frame} (@pxref{Visibility of Frames}); for text-only
+frames, it calls either @code{suspend-emacs} or @code{suspend-tty},
+depending on whether the frame is displayed on the controlling
+terminal device or not.
+@end deffn
+
 @node System Environment
 @section Operating System Environment
 @cindex operating system environment