path: root/devdocs/elisp/quitting.html

 <h3 class="section">Quitting</h3>    <p>Typing <kbd>C-g</kbd> while a Lisp function is running causes Emacs to <em>quit</em> whatever it is doing. This means that control returns to the innermost active command loop. </p> <p>Typing <kbd>C-g</kbd> while the command loop is waiting for keyboard input does not cause a quit; it acts as an ordinary input character. In the simplest case, you cannot tell the difference, because <kbd>C-g</kbd> normally runs the command <code>keyboard-quit</code>, whose effect is to quit. However, when <kbd>C-g</kbd> follows a prefix key, they combine to form an undefined key. The effect is to cancel the prefix key as well as any prefix argument. </p> <p>In the minibuffer, <kbd>C-g</kbd> has a different definition: it aborts out of the minibuffer. This means, in effect, that it exits the minibuffer and then quits. (Simply quitting would return to the command loop <em>within</em> the minibuffer.) The reason why <kbd>C-g</kbd> does not quit directly when the command reader is reading input is so that its meaning can be redefined in the minibuffer in this way. <kbd>C-g</kbd> following a prefix key is not redefined in the minibuffer, and it has its normal effect of canceling the prefix key and prefix argument. This too would not be possible if <kbd>C-g</kbd> always quit directly. </p> <p>When <kbd>C-g</kbd> does directly quit, it does so by setting the variable <code>quit-flag</code> to <code>t</code>. Emacs checks this variable at appropriate times and quits if it is not <code>nil</code>. Setting <code>quit-flag</code> non-<code>nil</code> in any way thus causes a quit. </p> <p>At the level of C code, quitting cannot happen just anywhere; only at the special places that check <code>quit-flag</code>. The reason for this is that quitting at other places might leave an inconsistency in Emacs’s internal state. Because quitting is delayed until a safe place, quitting cannot make Emacs crash. </p> <p>Certain functions such as <code>read-key-sequence</code> or <code>read-quoted-char</code> prevent quitting entirely even though they wait for input. Instead of quitting, <kbd>C-g</kbd> serves as the requested input. In the case of <code>read-key-sequence</code>, this serves to bring about the special behavior of <kbd>C-g</kbd> in the command loop. In the case of <code>read-quoted-char</code>, this is so that <kbd>C-q</kbd> can be used to quote a <kbd>C-g</kbd>. </p>  <p>You can prevent quitting for a portion of a Lisp function by binding the variable <code>inhibit-quit</code> to a non-<code>nil</code> value. Then, although <kbd>C-g</kbd> still sets <code>quit-flag</code> to <code>t</code> as usual, the usual result of this—a quit—is prevented. Eventually, <code>inhibit-quit</code> will become <code>nil</code> again, such as when its binding is unwound at the end of a <code>let</code> form. At that time, if <code>quit-flag</code> is still non-<code>nil</code>, the requested quit happens immediately. This behavior is ideal when you wish to make sure that quitting does not happen within a critical section of the program. </p>  <p>In some functions (such as <code>read-quoted-char</code>), <kbd>C-g</kbd> is handled in a special way that does not involve quitting. This is done by reading the input with <code>inhibit-quit</code> bound to <code>t</code>, and setting <code>quit-flag</code> to <code>nil</code> before <code>inhibit-quit</code> becomes <code>nil</code> again. This excerpt from the definition of <code>read-quoted-char</code> shows how this is done; it also shows that normal quitting is permitted after the first character of input. </p> <div class="example"> <pre class="example">(defun read-quoted-char (&amp;optional prompt)
  "…<var>documentation</var>…"
  (let ((message-log-max nil) done (first t) (code 0) char)
    (while (not done)
      (let ((inhibit-quit first)
            …)
        (and prompt (message "%s-" prompt))
        (setq char (read-event))
        (if inhibit-quit (setq quit-flag nil)))
      <span class="roman">…set the variable <code>code</code>…</span>)
    code))
</pre>
</div> <dl> <dt id="quit-flag">Variable: <strong>quit-flag</strong>
</dt> <dd><p>If this variable is non-<code>nil</code>, then Emacs quits immediately, unless <code>inhibit-quit</code> is non-<code>nil</code>. Typing <kbd>C-g</kbd> ordinarily sets <code>quit-flag</code> non-<code>nil</code>, regardless of <code>inhibit-quit</code>. </p></dd>
</dl> <dl> <dt id="inhibit-quit">Variable: <strong>inhibit-quit</strong>
</dt> <dd><p>This variable determines whether Emacs should quit when <code>quit-flag</code> is set to a value other than <code>nil</code>. If <code>inhibit-quit</code> is non-<code>nil</code>, then <code>quit-flag</code> has no special effect. </p></dd>
</dl> <dl> <dt id="with-local-quit">Macro: <strong>with-local-quit</strong> <em>body…</em>
</dt> <dd>
<p>This macro executes <var>body</var> forms in sequence, but allows quitting, at least locally, within <var>body</var> even if <code>inhibit-quit</code> was non-<code>nil</code> outside this construct. It returns the value of the last form in <var>body</var>, unless exited by quitting, in which case it returns <code>nil</code>. </p> <p>If <code>inhibit-quit</code> is <code>nil</code> on entry to <code>with-local-quit</code>, it only executes the <var>body</var>, and setting <code>quit-flag</code> causes a normal quit. However, if <code>inhibit-quit</code> is non-<code>nil</code> so that ordinary quitting is delayed, a non-<code>nil</code> <code>quit-flag</code> triggers a special kind of local quit. This ends the execution of <var>body</var> and exits the <code>with-local-quit</code> body with <code>quit-flag</code> still non-<code>nil</code>, so that another (ordinary) quit will happen as soon as that is allowed. If <code>quit-flag</code> is already non-<code>nil</code> at the beginning of <var>body</var>, the local quit happens immediately and the body doesn’t execute at all. </p> <p>This macro is mainly useful in functions that can be called from timers, process filters, process sentinels, <code>pre-command-hook</code>, <code>post-command-hook</code>, and other places where <code>inhibit-quit</code> is normally bound to <code>t</code>. </p>
</dd>
</dl> <dl> <dt id="keyboard-quit">Command: <strong>keyboard-quit</strong>
</dt> <dd><p>This function signals the <code>quit</code> condition with <code>(signal 'quit
nil)</code>. This is the same thing that quitting does. (See <code>signal</code> in <a href="errors">Errors</a>.) </p></dd>
</dl> <p>To quit without aborting a keyboard macro definition or execution, you can signal the <code>minibuffer-quit</code> condition. This has almost the same effect as the <code>quit</code> condition except that the error handling in the command loop handles it without exiting keyboard macro definition or execution. </p> <p>You can specify a character other than <kbd>C-g</kbd> to use for quitting. See the function <code>set-input-mode</code> in <a href="input-modes">Input Modes</a>. </p><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 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/Quitting.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Quitting.html</a>
  </p>
</div>