From a5fb033b9ac0a2573347d37f6950fbab52544d65 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 7 Sep 2024 18:38:40 +0300 Subject: [PATCH] ; Improve documentation of 'suspend-emacs' * doc/lispref/os.texi (Suspending Emacs): * src/keyboard.c (Fsuspend_emacs): Document possible failures in sending STUFFSTRING to the shell. (Bug#73100). (cherry picked from commit 4f044d0d3df019e9a7717b443fe4b4c172854c7c) --- doc/lispref/os.texi | 13 +++++++------ src/keyboard.c | 7 ++++++- 2 files changed, 13 insertions(+), 7 deletions(-) diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 3ab4b66ba30..fe84c2c3403 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -811,9 +811,6 @@ before suspending Emacs, or this function signals an error. If @var{string} is non-@code{nil}, its characters are sent to Emacs's superior shell, to be read as terminal input. -@c FIXME? It seems to me that shell does echo STRING. -The characters in @var{string} are not echoed by the superior shell; -only the results appear. Before suspending, @code{suspend-emacs} runs the normal hook @code{suspend-hook}. After the user resumes Emacs, @@ -859,9 +856,13 @@ Resumed! @end group @end smallexample -@c FIXME? AFAICS, it is echoed. -Note that @samp{pwd} is not echoed after Emacs is suspended. But it -is read and executed by the shell. +Note that on some operating systems, sending @var{string} to the Emacs +parent shell might require special privileges, in which case it might +silently fail to send @var{string} to the shell for execution. On other +systems this is not supported, and Emacs will signal an error if you +try. Also, @var{string} might not be echoed, even if it is executed by +the shell. So we don't recommend relying on this feature in portable +Lisp programs. @end deffn @defvar suspend-hook diff --git a/src/keyboard.c b/src/keyboard.c index a6bd113f19e..64c9fe8b2dc 100644 --- a/src/keyboard.c +++ b/src/keyboard.c @@ -11917,7 +11917,12 @@ Before suspending, run the normal hook `suspend-hook'. After resumption run the normal hook `suspend-resume-hook'. Some operating systems cannot stop the Emacs process and resume it later. -On such systems, Emacs starts a subshell instead of suspending. */) +On such systems, Emacs starts a subshell instead of suspending. + +On some operating systems, stuffing characters into terminal input +buffer requires special privileges or is not supported at all. +On such systems, calling this function with non-nil STUFFSTRING might +either signal an error or silently fail to stuff the characters. */) (Lisp_Object stuffstring) { specpdl_ref count = SPECPDL_INDEX (); -- 2.39.2