diff options
Diffstat (limited to 'devdocs/elisp/suspending-emacs.html')
| -rw-r--r-- | devdocs/elisp/suspending-emacs.html | 46 |
1 files changed, 46 insertions, 0 deletions
diff --git a/devdocs/elisp/suspending-emacs.html b/devdocs/elisp/suspending-emacs.html new file mode 100644 index 00000000..fe021eb0 --- /dev/null +++ b/devdocs/elisp/suspending-emacs.html @@ -0,0 +1,46 @@ + <h4 class="subsection">Suspending Emacs</h4> <p>On text terminals, it is possible to <em>suspend Emacs</em>, which means stopping Emacs temporarily and returning control to its superior process, which is usually the shell. This allows you to resume editing later in the same Emacs process, with the 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</code>. </p> <p>Suspending works only on a terminal device from which the Emacs session was started. We call that device the <em>controlling terminal</em> of the session. Suspending is not allowed if the controlling terminal is a graphical terminal. Suspending is usually not relevant in graphical environments, since you can simply switch to another application without doing anything special to Emacs. </p> <p>Some operating systems (those without <code>SIGTSTP</code>, or MS-DOS) 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. </p> <dl> <dt id="suspend-emacs">Command: <strong>suspend-emacs</strong> <em>&optional string</em> +</dt> <dd> +<p>This function stops Emacs and returns control to the superior process. If and when the superior process resumes Emacs, <code>suspend-emacs</code> returns <code>nil</code> to its caller in Lisp. </p> <p>This function works only on the controlling terminal of the Emacs session; to relinquish control of other tty devices, use <code>suspend-tty</code> (see below). If the Emacs session uses more than one terminal, you must delete the frames on all the other terminals before suspending Emacs, or this function signals an error. See <a href="multiple-terminals">Multiple Terminals</a>. </p> <p>If <var>string</var> is non-<code>nil</code>, its characters are sent to Emacs’s superior shell, to be read as terminal input. The characters in <var>string</var> are not echoed by the superior shell; only the results appear. </p> <p>Before suspending, <code>suspend-emacs</code> runs the normal hook <code>suspend-hook</code>. After the user resumes Emacs, <code>suspend-emacs</code> runs the normal hook <code>suspend-resume-hook</code>. See <a href="hooks">Hooks</a>. </p> <p>The next redisplay after resumption will redraw the entire screen, unless the variable <code>no-redraw-on-reenter</code> is non-<code>nil</code>. See <a href="refresh-screen">Refresh Screen</a>. </p> <p>Here is an example of how you could use these hooks: </p> <div class="example"> <pre class="example">(add-hook 'suspend-hook + (lambda () (or (y-or-n-p "Really suspend?") + (error "Suspend canceled")))) +</pre> +<pre class="example">(add-hook 'suspend-resume-hook (lambda () (message "Resumed!") + (sit-for 2))) +</pre> +</div> <p>Here is what you would see upon evaluating <code>(suspend-emacs "pwd")</code>: </p> <div class="example"> <pre class="example">---------- Buffer: Minibuffer ---------- +Really suspend? <kbd>y</kbd> +---------- Buffer: Minibuffer ---------- +</pre> + +<pre class="example">---------- Parent Shell ---------- +bash$ /home/username +bash$ fg +</pre> + +<pre class="example">---------- Echo Area ---------- +Resumed! +</pre> +</div> <p>Note that ‘<samp>pwd</samp>’ is not echoed after Emacs is suspended. But it is read and executed by the shell. </p> +</dd> +</dl> <dl> <dt id="suspend-hook">Variable: <strong>suspend-hook</strong> +</dt> <dd><p>This variable is a normal hook that Emacs runs before suspending. </p></dd> +</dl> <dl> <dt id="suspend-resume-hook">Variable: <strong>suspend-resume-hook</strong> +</dt> <dd><p>This variable is a normal hook that Emacs runs on resuming after a suspension. </p></dd> +</dl> <dl> <dt id="suspend-tty">Function: <strong>suspend-tty</strong> <em>&optional tty</em> +</dt> <dd> +<p>If <var>tty</var> 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. <var>tty</var> can be a terminal object, a frame (meaning the terminal for that frame), or <code>nil</code> (meaning the terminal for the selected frame). See <a href="multiple-terminals">Multiple Terminals</a>. </p> <p>If <var>tty</var> is already suspended, this function does nothing. </p> <p>This function runs the hook <code>suspend-tty-functions</code>, passing the terminal object as an argument to each function. </p> +</dd> +</dl> <dl> <dt id="resume-tty">Function: <strong>resume-tty</strong> <em>&optional tty</em> +</dt> <dd> +<p>This function resumes the previously suspended terminal device <var>tty</var>; where <var>tty</var> has the same possible values as it does for <code>suspend-tty</code>. </p> <p>This function reopens the terminal device, re-initializes it, and redraws it with that terminal’s selected frame. It then runs the hook <code>resume-tty-functions</code>, passing the terminal object as an argument to each function. </p> <p>If the same device is already used by another Emacs terminal, this function signals an error. If <var>tty</var> is not suspended, this function does nothing. </p> +</dd> +</dl> <dl> <dt id="controlling-tty-p">Function: <strong>controlling-tty-p</strong> <em>&optional tty</em> +</dt> <dd><p>This function returns non-<code>nil</code> if <var>tty</var> is the controlling terminal of the Emacs session; <var>tty</var> can be a terminal object, a frame (meaning the terminal for that frame), or <code>nil</code> (meaning the terminal for the selected frame). </p></dd> +</dl> <dl> <dt id="suspend-frame">Command: <strong>suspend-frame</strong> +</dt> <dd><p>This command <em>suspends</em> a frame. For GUI frames, it calls <code>iconify-frame</code> (see <a href="visibility-of-frames">Visibility of Frames</a>); for frames on text terminals, it calls either <code>suspend-emacs</code> or <code>suspend-tty</code>, depending on whether the frame is displayed on the controlling terminal device or not. </p></dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Suspending-Emacs.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Suspending-Emacs.html</a> + </p> +</div> |