[Emacs-diffs] emacs/doc/lispref os.texi

[Eli Zaretskii]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Eli Zaretskii <eliz>    09/01/17 18:43:59

Modified files:
        doc/lispref    : os.texi 

Log message:
        (Suspending Emacs): Update for multi-tty; document `suspend-tty',
        `resume-tty', and `controlling-tty-p'.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/os.texi?cvsroot=emacs&r1=1.19&r2=1.20

Patches:
Index: os.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/doc/lispref/os.texi,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -b -r1.19 -r1.20
--- os.texi     17 Jan 2009 15:35:55 -0000      1.19
+++ os.texi     17 Jan 2009 18:43:59 -0000      1.20
@@ -577,6 +577,11 @@
 resume Emacs, use the appropriate command in the parent shell---most
 likely @code{fg}.
 
address@hidden 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 @@
 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
address@hidden (@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 address@hidden, 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 @@
 after a suspension.
 @end defvar
 
address@hidden 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
address@hidden).
address@hidden defun
+
address@hidden resume-tty &optional tty
+Resume the previously suspended terminal device @var{tty}.  If
address@hidden is a frame, it means resume that frame's terminal;
address@hidden 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.
address@hidden defun
+
address@hidden controlling-tty-p &optional terminal
+This function returns address@hidden if @var{terminal} is the
+controlling terminal device of the Emacs session.
address@hidden defun
+
address@hidden Command suspend-frame
+This command @dfn{suspends} a frame.  For GUI frames, it calls
address@hidden (@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.
address@hidden deffn
+
 @node System Environment
 @section Operating System Environment
 @cindex operating system environment